Tutoriel · Données des joueurs

Comment sauvegarder les données des joueurs sur Roblox Studio avec les DataStores

Roblox ne garde rien d'un joueur d'une session à l'autre, sauf si un script serveur le sauvegarde. Ce guide construit un module PlayerData qui charge, garde en mémoire et sauvegarde les données de chaque joueur avec DataStoreService, puis couvre les tests, les limites et les façons dont des données sauvegardées se perdent.

Mis à jour le 12 novembre 202620 min de lectureÉcrit par

En bref

Utilise DataStoreService depuis un Script serveur : charge les données de chaque joueur avec GetAsync quand il arrive, garde-les dans une table pendant qu'il joue, et sauvegarde-les avec UpdateAsync à intervalles réguliers, quand il part (PlayerRemoving) et quand le serveur s'arrête (game:BindToClose). Mets chaque appel dans un pcall et réessaie quelques fois en cas d'échec.

  • Pour tester dans Studio, publie le jeu et active File > Experience Settings > Security > Enable Studio Access to API Services, dans un jeu de test séparé : Studio utilise les mêmes données que les serveurs du jeu publié.
  • Si les données d'un joueur ne se chargent pas, ne sauvegarde jamais ce joueur. Sauvegarder les valeurs par défaut écraserait sa vraie progression.
  • Sauvegarde une table par joueur sous une clé comme User_12345, à intervalles réguliers plutôt qu'à chaque changement.
  • Pour les échanges ou les objets payants, ajoute un verrouillage de session pour que deux serveurs ne puissent pas sauvegarder le même joueur.
Sur cette page
  1. Activer l'accès Studio
  2. Fonctionnement des data stores
  3. GetAsync vs UpdateAsync
  4. 1. Module PlayerData
  5. Fonctionnement du module
  6. 2. Utiliser les données
  7. 3. Prévenir le joueur
  8. 4. Tester dans Studio
  9. Pertes de données
  10. Verrouillage de session
  11. Limites
  12. Versions et copies
  13. Problèmes courants
  14. Avec RoCode
  15. Questions fréquentes
  16. Sources et lectures

Avant de commencer : activer l'accès dans Studio sur une copie de test

Un jeu qui tourne dans Studio ne peut pas accéder aux data stores tant que tu ne l'autorises pas. L'autoriser a un piège que la documentation de Roblox signale : Studio lit et écrit alors les mêmes data stores que le jeu publié, donc un test qui remet tes pièces à zéro dans Studio les remet aussi à zéro dans le jeu publié, et un bug dans du code de test peut abîmer les clés de vrais joueurs.

  1. Fais une copie de test. Enregistre ton jeu dans un fichier, ouvre la copie, choisis File > Publish to Roblox As et clique sur Create new game. Ne l'ajoute pas comme place dans ton jeu publié : toutes les places d'un même jeu partagent les mêmes data stores.
  2. Dans la copie de test, ouvre File > Experience Settings et va dans Security.
  3. Active Enable Studio Access to API Services et clique sur Save.

Les appels aux data stores ne marchent que dans des Scripts serveur ; un LocalScript qui essaie reçoit une erreur, donc les clients ne peuvent pas écrire de données sauvegardées. Quand un bouton doit les changer, le client demande au serveur avec un RemoteEvent et c'est le serveur qui décide (vois le guide des RemoteEvents, en anglais).

Comment les data stores gardent les données des joueurs

Illustration animéeLe test de l'étape 4 du guide, en accéléré : Play, Stop sauvegarde la session dans le data store, et un nouveau Play la recharge, donc l'Output affiche 200.

Un data store est un ensemble nommé de clés et de valeurs sur les serveurs de Roblox, partagé par tous les serveurs et toutes les places de ton jeu. DataStoreService:GetDataStore("PlayerData") en renvoie un.

Les bonnes pratiques de Roblox se résument à un data store pour les données des joueurs, une clé par joueur, une table dans chaque clé. Construis la clé à partir du UserId du joueur, comme User_12345, jamais à partir de son nom, qu'il peut changer. Un format fixe User_{UserId} permet aussi au traitement automatique du droit à l'oubli de Roblox de trouver les données d'un joueur, si tu le configures.

Ce qu'un data store peut sauvegarder
TypeSauvegardé ?Notes
Nombres, chaînes, booléens, buffersOuiLes chaînes doivent être en UTF-8 valide. Ne sauvegarde pas inf ni nan.
TablesOuiSi tout ce qu'elles contiennent peut aussi être sauvegardé. Une table dont les clés numériques ne commencent pas à 1 (donc de longueur 0) revient avec ces clés en chaînes.
Instances, Vector3, CFrame, Color3NonLa sauvegarde plante ou enregistre nil. Sauvegarde le nom d'un objet, ou une position sous forme de trois nombres.

Chaque requête est un appel web qui peut échouer, prend du temps et compte dans un budget par minute. Les systèmes de sauvegarde fiables lisent donc une fois quand le joueur arrive, gardent les données dans une table serveur pendant qu'il joue, et les réécrivent de temps en temps.

GetAsync, SetAsync ou UpdateAsync : lequel utiliser

Les principales méthodes des data stores
MéthodeCe qu'elle faitÀ utiliser pour
GetAsync(key)Lit la valeur. Le résultat est gardé en cache sur ce serveur pendant 4 secondes.Charger les données d'un joueur
SetAsync(key, value)Écrase la valeur sans la lire. Une écriture.Une nouvelle clé, ou une valeur qui ne dépend pas de l'ancienne
UpdateAsync(key, callback)Lit la dernière valeur, la passe à ta fonction et écrit ce qu'elle renvoie. Une lecture et une écriture.Sauvegarder les données des joueurs, et toute clé que plusieurs serveurs peuvent écrire
IncrementAsync(key, delta)Ajoute un nombre entier à un nombre entier sauvegardé.Les compteurs
RemoveAsync(key)Supprime la clé et renvoie l'ancienne valeur. Les versions précédentes peuvent encore être listées et lues.Supprimer les données d'un joueur

SetAsync écrit à l'aveugle : si deux serveurs sauvegardent la même clé presque au même moment, la dernière écriture gagne, quel que soit son contenu. UpdateAsync lit d'abord la valeur actuelle, et si un autre serveur écrit entre-temps, Roblox relance ta fonction avec la nouvelle valeur. Roblox le recommande chaque fois qu'une écriture dépend de la valeur actuelle ou que plusieurs serveurs peuvent écrire la clé, ce qui décrit les données des joueurs. La fonction a trois règles :

  • Elle ne doit pas attendre : pas de task.wait() ni d'autres appels aux data stores à l'intérieur.
  • Elle peut tourner plusieurs fois, donc elle doit seulement calculer la nouvelle valeur, jamais donner d'objets ni déclencher d'événements.
  • Renvoyer nil annule l'écriture. Le module s'en sert pour ne pas écraser des données sauvegardées par une version plus récente du jeu.

Étape 1 : créer le module PlayerData

Ce ModuleScript est le seul code qui parle au data store. Il charge les données de chaque joueur quand il arrive, les garde en mémoire, les sauvegarde toutes les 180 secondes, quand le joueur part et quand le serveur s'arrête, et refuse de sauvegarder quelqu'un dont les données n'ont pas pu être chargées.

  1. Dans l'Explorer, survole ServerScriptService, clique sur + et insère un ModuleScript. Renomme-le PlayerData et remplace son contenu par le code ci-dessous.
  2. Un ModuleScript ne tourne que quand un script le require. Insère un Script dans ServerScriptService nommé Main avec cette ligne : local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Les autres scripts serveur le require de la même façon.
  3. Modifie DEFAULTS et le type Data pour qu'ils correspondent à ton jeu, en gardant chaque champ en nombre, chaîne, booléen ou table.
L'Explorer après les étapes 1 à 3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript dans ServerScriptService nommé PlayerData
-- PlayerData : charge les données de chaque joueur quand il arrive, les garde en mémoire,
-- et les sauvegarde à intervalles réguliers, quand il part et quand le serveur s'arrête.
-- Les autres scripts serveur utilisent PlayerData.Get(player) pour les lire et les modifier.

local Players = game:GetService("Players")
local DataStoreService = game:GetService("DataStoreService")
local RunService = game:GetService("RunService")

local STORE_NAME = "PlayerData"
local SCHEMA_VERSION = 2 -- augmente-le quand la forme des données change, et ajoute une étape à migrate()
local AUTOSAVE_SECONDS = 180
-- Dans Studio, un appel raté abandonne tout de suite, donc tester sans accès aux data stores va vite
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- double après chaque échec : 1, 2, 4

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

-- Ce avec quoi commence un tout nouveau joueur
local DEFAULTS: { [string]: any } = {
	Coins = 0,
	Level = 1,
	Inventory = {},
}

type Session = {
	key: string,
	userId: number,
	data: Data,
	canSave: boolean, -- false si le chargement a échoué : les données par défaut ne doivent jamais remplacer une vraie progression
}

-- Appelée dans chaque pcall ci-dessous, pour qu'un jeu pas encore publié
-- (sans accès aux data stores) charge quand même les joueurs avec les données par défaut
local function store(): DataStore
	return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- sauvegardes encore en cours, par clé
local loadedEvent = Instance.new("BindableEvent")

local PlayerData = {}

-- Se déclenche avec le joueur une fois ses données prêtes. Appelle PlayerData.Get(player) pour la table :
-- une table envoyée par un BindableEvent arrive en copie, donc la modifier ne changerait rien.
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) -- une copie neuve, pour que les joueurs ne partagent jamais une même table Inventory
	data.SchemaVersion = SCHEMA_VERSION
	return data
end

-- Met les données sauvegardées au schéma actuel. Renvoie nil si elles ne peuvent pas être utilisées sans risque.
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 -- sauvegardé par une version plus récente du jeu : ne jamais le charger ni l'écraser ici
	end

	-- Une étape par changement de schéma, la plus ancienne d'abord
	if version < 2 then
		-- Exemple : la version 1 appelait la monnaie Gold. Ne la copie que si Coins manque,
		-- pour que les anciennes données qui ont déjà Coins mais pas de SchemaVersion gardent leur valeur.
		if saved.Coins == nil then
			saved.Coins = saved.Gold
		end
		saved.Gold = nil
	end

	-- Ajoute les champs créés depuis la dernière sauvegarde du joueur, et remplace les valeurs du mauvais 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

-- Lance un appel au data store dans un pcall. En cas d'échec, attend et réessaie, en doublant
-- l'attente à chaque fois et en ajoutant un peu de hasard pour que les serveurs ne réessaient pas tous ensemble.
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 -- renvoyer nil annule l'écriture
			end
			-- Écrit toute la table actuelle, marquée avec le UserId du joueur
			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()
		-- Commence à un moment au hasard dans l'intervalle pour que les serveurs ne sauvegardent pas tous en même temps
		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

	-- Si ce joueur vient de quitter ce serveur et revient, laisse d'abord la dernière sauvegarde se terminer
	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 -- parti pendant le chargement : rien n'a changé, donc il n'y a rien à sauvegarder
	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) -- une interface peut le lire et prévenir le joueur
	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 -- arrête la boucle d'autosave et fait qu'un deuxième appel ne fait rien
	save(session)
end

-- La table de données en direct du joueur, ou nil tant qu'elle n'est pas chargée. À modifier depuis des scripts serveur uniquement.
function PlayerData.Get(player: Player): Data?
	local session = sessions[player]
	return if session then session.data else nil
end

-- True quand les données du joueur ont été chargées et seront sauvegardées. Vérifie-le avant de vendre quoi que ce soit.
function PlayerData.CanSave(player: Player): boolean
	local session = sessions[player]
	return session ~= nil and session.canSave
end

-- Sauvegarde tout de suite au lieu d'attendre l'intervalle, pour les moments qui comptent comme un achat.
-- Attend, et renvoie true une fois la sauvegarde passée.
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) -- les joueurs arrivés avant le premier require de ce module
end

game:BindToClose(function()
	-- Le serveur donne 30 secondes à ces fonctions, donc on sauvegarde tout le monde en même temps
	for player in sessions do
		task.spawn(endSession, player)
	end
	-- Puis on attend chaque sauvegarde encore en cours, y compris celles lancées par PlayerRemoving
	while next(pendingSaves) do
		task.wait()
	end
end)

return PlayerData

Une fois le jeu publié, garde le même STORE_NAME et le même format de clé User_. Changer l'un ou l'autre fait pointer le module vers des clés vides, et chaque joueur repart des valeurs par défaut.

Comment le module protège les données

Des valeurs par défaut et une version de schéma

Un nouveau joueur reçoit une copie neuve de DEFAULTS. Ce doit être une copie : si tous les joueurs partageaient une même table Inventory, un objet ajouté pour l'un apparaîtrait chez tous.

Chaque table sauvegardée porte un SchemaVersion. Ajouter un champ ne demande pas de changer de version, parce que migrate remplit les champs manquants à partir des valeurs par défaut. Renommer ou restructurer en demande une : augmente SCHEMA_VERSION et ajoute une étape, comme l'exemple qui renomme Gold en Coins (dans un nouveau jeu, supprime-le et commence à 1). Des données avec une version plus haute que celle du serveur viennent d'une nouvelle version du jeu encore en cours de déploiement, donc les anciens serveurs n'y touchent pas.

Un chargement raté n'est jamais sauvegardé

Cette règle évite les effacements complets. Si toutes les tentatives de chargement échouent, le joueur joue avec les données par défaut, mais canSave vaut false, donc ces valeurs par défaut n'écrasent jamais sa vraie progression. Le module règle aussi un attribut DataLoaded sur false, que l'étape 3 utilise pour le prévenir. L'exemple de référence de Roblox gère les chargements ratés de la même façon et le conseille plutôt que d'expulser le joueur ; si tu préfères l'expulser, appelle player:Kick() avec un message là où le module affiche son avertissement.

Des nouvelles tentatives avec un délai croissant

withRetries met chaque appel dans un pcall. Après un échec, il attend 1, puis 2, puis 4 secondes, chaque fois plus jusqu'à la moitié de ce temps au hasard, et s'arrête après quatre tentatives (une dans Studio, pour qu'un jeu sans accès aux data stores démarre tout de suite). Le hasard étale les nouvelles tentatives de nombreux serveurs après une panne, et la limite garde l'attente autour de 10 secondes, dans les 30 secondes qu'a un serveur pour s'arrêter. Comme chaque sauvegarde écrit toute la table en direct avec UpdateAsync, une nouvelle tentative qui finit en retard ne peut pas remettre d'anciennes données.

Quand il sauvegarde

QuandPourquoi
Toutes les 180 secondes tant que le joueur est sur le serveurLimite la perte en cas de plantage. La première sauvegarde arrive à un moment au hasard dans l'intervalle pour que les serveurs ne sauvegardent pas tous en même temps. L'exemple de référence de Roblox utilise aussi 180 secondes.
Quand le joueur part (PlayerRemoving)La sauvegarde finale normale. La session est retirée d'abord, donc l'autosave s'arrête.
Quand le serveur s'arrête (game:BindToClose)Tous ceux encore sur le serveur sont sauvegardés en même temps, et la fonction attend chaque sauvegarde en cours. Roblox lui donne 30 secondes.
À la demande, avec PlayerData.SaveNow(player)Après quelque chose qui ne doit pas être perdu, comme un achat.

Si un joueur revient sur le même serveur pendant que sa sauvegarde finale tourne encore, le nouveau chargement attend la fin de cette sauvegarde, donc il ne peut pas lire l'ancienne valeur.

Étape 2 : lire et modifier les données depuis d'autres scripts

Chaque script serveur qui require le module partage les mêmes tables :

AppelCe qu'il fait
PlayerData.Get(player)La table de données en direct du joueur, ou nil tant qu'elle n'est pas chargée. Modifie directement les champs, comme data.Coins += 10, et la sauvegarde suivante en tient compte.
PlayerData.LoadedSe déclenche avec le joueur une fois ses données prêtes, y compris après un chargement raté. Il ne passe que le joueur, parce qu'une table envoyée par un BindableEvent arrive en copie.
PlayerData.CanSave(player)false si le chargement a échoué. Vérifie-le avant de vendre quoi que ce soit : un achat qui ne peut pas être sauvegardé disparaît quand le joueur part.
PlayerData.SaveNow(player)Sauvegarde tout de suite et renvoie true si ça a marché. Il attend.

Le module est le seul endroit où vivent les données sauvegardées, et leaderstats n'est qu'un affichage : construis-le comme dans le guide du leaderboard, remplis-le à partir de PlayerData.Get(player) dans une fonction connectée à Loaded, et mets à jour les deux quand une valeur change. Ne relis jamais les valeurs sauvegardées depuis leaderstats, et ne laisse jamais un deuxième script sauvegarder la même clé.

Un script qui require le module après l'arrivée des joueurs rate leur Loaded. Connecte la fonction, puis parcours aussi Players:GetPlayers() et traite chaque joueur pour qui PlayerData.Get(player) renvoie déjà une table.

Tu remplaces un ancien script de sauvegarde, comme celui du guide du leaderboard ? Ses valeurs restent dans son propre data store et sous sa propre clé, donc ce module fait repartir tout le monde des valeurs par défaut. Avant le lancement, fais pointer STORE_NAME et le préfixe User_ vers les anciens (migrate traite des données sans SchemaVersion comme la version 1 et remplit les champs manquants), ou recopie les anciennes valeurs, puis retire l'ancien script.

Les clients ne modifient jamais ces données directement. Un bouton de boutique déclenche un RemoteEvent ; le serveur vérifie CanSave, compare le prix avec les Coins du joueur, modifie la table et appelle SaveNow. Le guide de la boutique construit ce processus d'achat côté serveur.

Pour un exemple concret d'ajout de champs, le guide du simulateur de clics ajoute PowerLevel et Rebirths à DEFAULTS et au type Data, puis les modifie dans la table que renvoie PlayerData.Get. migrate donne les nouveaux champs aux joueurs qui ont d'anciennes sauvegardes.

Étape 3 : prévenir le joueur quand ses données ne se sont pas chargées

Un joueur dont les données ne se sont pas chargées doit savoir que cette session ne sera pas sauvegardée, pour revenir plus tard au lieu de jouer pour rien. Ce LocalScript surveille l'attribut DataLoaded et affiche une bannière quand il vaut false.

LocalScript dans StarterPlayerScripts nommé 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

-- Le serveur règle DataLoaded une fois, après avoir essayé de charger les données de ce joueur
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

Étape 4 : tester la sauvegarde dans Studio

Fais-le dans la copie de test, avec l'accès Studio activé.

  1. Donne-toi quelque chose à sauvegarder. Sous la ligne du require dans Main, ajoute : PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end)
  2. Appuie sur Play. La fenêtre Output (dans le menu Window, ou dans l'onglet Script) affiche ton nom et 100 (au premier lancement), sans avertissement Could not load.
  3. Appuie sur Stop. Terminer le test ferme le serveur, et le module te sauvegarde avant qu'il se ferme.
  4. Appuie de nouveau sur Play. L'Output doit afficher 200, 100 de plus que la dernière fois. S'il affiche de nouveau le même nombre, la sauvegarde n'est pas passée : lis les avertissements au-dessus.
  5. Teste le cas d'échec. Désactive l'accès Studio et appuie sur Play. Après plusieurs secondes de nouvelles tentatives, l'Output affiche Could not load User_... et 100, et la bannière de l'étape 3 apparaît. Arrête, réactive l'accès et appuie sur Play : l'Output affiche 300, tes 200 sauvegardés plus 100, parce que la session ratée n'a jamais été sauvegardée par-dessus tes données.
  6. Retire la ligne de test de Main.

Pourquoi les données des joueurs se perdent

Voici les façons habituelles dont un système de sauvegarde perd de la progression. Le module gère dans son code les quatre premières lignes et celle du schéma ; les autres dépendent de ce que tu sauvegardes et de la façon dont tu t'en sers, et la dernière demande un verrouillage de session.

Ce qui se passeRésultatPrévention
Un chargement échoue et le script sauvegarde quand mêmeLes valeurs par défaut écrasent la vraie progression : un effacement completNe jamais sauvegarder un joueur dont le chargement a échoué
Sauvegarder seulement dans PlayerRemovingUn plantage ou un arrêt saute la sauvegardeUne autosave, plus un BindToClose qui attend ses sauvegardes
Pas de pcall ou pas de nouvelle tentativeUne seule requête ratée arrête le script ou perd la sauvegardeUn pcall avec quelques nouvelles tentatives espacées
Sauvegarder à chaque changementLes requêtes s'accumulent ; quand une file en contient 30, les nouvelles sont abandonnéesGarder les données en mémoire et sauvegarder à intervalles réguliers
Sauvegarder quelque chose qu'un data store ne peut pas contenirLa sauvegarde plante, ou la valeur revient à nilSauvegarder des nombres, des chaînes, des booléens et des tables de ces types
Changer la forme des données sans migrationLes anciennes sauvegardes se chargent dans les mauvais champsUne version de schéma et une étape de migration
Deux scripts qui sauvegardent la même cléChaque sauvegarde écrase les champs de l'autreUn seul module possède la clé
Deux serveurs qui ont le même joueurLe serveur aux données plus anciennes sauvegarde en dernier et écrase une progression plus récenteLe verrouillage de session

Verrouillage de session, « lock lost » et ProfileStore

Un joueur n'est connecté qu'à un serveur à la fois, mais la sauvegarde finale de l'ancien serveur peut encore tourner quand il en rejoint un nouveau : une nouvelle tentative lente, une téléportation ou un retour rapide. Si le nouveau serveur charge en premier, il a des données plus anciennes, et c'est le serveur qui sauvegarde en dernier qui gagne. La documentation de Roblox note que dans les jeux avec des échanges, cet écart est une source fréquente de duplication d'objets.

Le verrouillage de session (session locking) le comble. Quand un serveur charge la clé d'un joueur, il écrit son propre identifiant de verrou dans les métadonnées de la clé, dans le même appel UpdateAsync. Tout autre serveur qui trouve un verrou non expiré qu'il n'a pas posé ne charge pas et ne sauvegarde pas la clé. Le propriétaire rafraîchit le verrou à chaque autosave et le retire dans la sauvegarde finale ; s'il arrête de le rafraîchir, le verrou expire et un autre serveur peut le prendre.

Ce que veut dire « lock lost »

Dans un système à verrouillage de session, un serveur a perdu le verrou quand un autre serveur possède maintenant la clé du joueur, parce que le verrou a expiré ou a été repris. Sa copie n'est peut-être plus à jour, donc il doit arrêter de sauvegarder ce joueur ; une réponse courante est de l'expulser avec un message pour qu'il se reconnecte. Si tu as vu « lock lost » en tant que joueur, ça vient du système de sauvegarde de ce jeu, et seuls ses développeurs peuvent l'expliquer.

En as-tu besoin ?

Le module de ce guide ne verrouille pas les sessions. Sans verrouillage, le pire cas réaliste est qu'un joueur perde, dans une rare situation de course, ce qu'il a gagné sur l'ancien serveur depuis sa dernière sauvegarde réussie. Ajoute un verrouillage quand une duplication ou une perte coûterait quelque chose de réel aux joueurs : des échanges, des developer products, des objets rares ou des téléportations fréquentes.

OptionCe que c'estBon à savoir
Le module de ce guideChargement, mise en mémoire, nouvelles tentatives, autosave, sauvegardes à l'arrêt et versions de schéma, sans verrouillageAssez court pour être lu en entier et modifié
L'exemple de Roblox pour les données des joueurs et les achatsDu code de référence de Roblox avec verrouillage de session, nouvelles tentatives traitées dans l'ordre pour chaque clé, et gestion des reçus d'achatRoblox dit qu'il n'a pas fait ses preuves sur la durée dans un jeu populaire et qu'il ne faut pas l'utiliser tel quel sans tests approfondis
ProfileStoreUn module communautaire gratuit et open source, le successeur de ProfileService, construit autour du verrouillage de session et de l'autosavePas fait par Roblox. Faire passer un jeu existant dessus veut dire migrer les données déjà sauvegardées

Pour tout module tiers, Roblox conseille de vérifier à qui il appartient, s'il est maintenu, et comment tu accéderais à tes données sans lui. La même documentation qualifie DataStore2 de bibliothèque ancienne que les nouveaux jeux ne devraient pas utiliser.

Les limites des data stores

Voici les limites de la documentation de Roblox au 30 septembre 2026. Roblox les révise, donc consulte la page des codes d'erreur et des limites (en anglais) avant de concevoir autour d'un nombre exact.

Limites de requêtes par défaut pour chaque serveur, par minute
Type de requêteData stores standardOrdered data stores
Lecture : GetAsync, la lecture dans UpdateAsync60 + 40 × joueurs60 + 40 × joueurs
Écriture : SetAsync, IncrementAsync, l'écriture dans UpdateAsync60 + 40 × joueurs30 + 5 × joueurs
Liste : ListKeysAsync, ou GetSortedAsync pour les stores ordonnés5 + 2 × joueurs5 + 2 × joueurs
Suppression : RemoveAsync60 + 40 × joueurs30 + 5 × joueurs

Avec 20 joueurs, un serveur peut faire 860 écritures standard par minute ; l'autosave de ce module en utilise environ 7, plus une par joueur qui part. C'est sauvegarder à chaque pièce ramassée qui épuise un budget. Un deuxième budget couvre tout le jeu et est partagé avec Open Cloud : 300 lectures par minute plus 40 par joueur en ligne, et 300 écritures plus 20 par joueur.

Limites de taille et de débit
LimiteValeur
Nom du data store, nom de clé, scope50 caractères chacun
Valeur sauvegardée dans une clé4 194 304 caractères, mesurés en JSON
Lectures d'une clé, tous serveurs confondus25 Mo par minute
Écritures dans une clé, tous serveurs confondus4 Mo par minute, chaque requête arrondie au Ko supérieur
Requêtes en attente30 par file ; au-delà, les requêtes échouent avec les erreurs 301 à 306
Stockage pour tout le jeu500 Mo plus 1 Mo par utilisateur sur toute la vie du jeu

Mesure les données d'un joueur avec #HttpService:JSONEncode(data), et vois le budget restant d'un serveur en cours avec DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). Les appels GetAsync servis par le cache de 4 secondes ne comptent pas. Le mode Run de Studio a ses propres limites, peut-être plus basses, donc Roblox conseille Team Create pour tester les limites de requêtes.

Versions et copies de sauvegarde

Les data stores standard gardent un historique pour toi. La première écriture dans une clé à chaque heure UTC est gardée comme version, et les écritures suivantes dans cette heure s'écrasent entre elles. Une ancienne version expire 30 jours après qu'une écriture plus récente l'a remplacée ; la dernière n'expire jamais. Les ordered data stores ne gardent pas de versions.

Pour revenir en arrière sur un joueur, ouvre Data Stores Manager (Creations, ton jeu, Configure > Data Stores Manager), sélectionne sa clé, choisis une version précédente et clique sur Revert, ce qui demande la permission Edit. Fais-le pendant que le joueur est hors ligne, sinon le serveur qui a sa session sauvegardera sa copie par-dessus le retour en arrière. Depuis un script serveur, ListVersionsAsync et GetVersionAsync trouvent et lisent une ancienne version, que tu réécris ensuite comme valeur actuelle.

Avant de publier une mise à jour qui change la façon dont les données sont sauvegardées, Roblox recommande un snapshot avec l'API Open Cloud Snapshot Data Stores (un par jour et par jeu). Sans snapshot, une sauvegarde boguée à 3 h 30 UTC écrase tout ce qui a été écrit dans cette clé depuis 3 h 00, parce qu'elle tombe dans la même version horaire.

Problèmes courants

Les erreurs de data store apparaissent dans la fenêtre Output de Studio, et le module affiche un avertissement avec le texte d'erreur de Roblox à chaque tentative ratée. Le guide des erreurs de script explique comment lire l'Output en général.

StudioAccessToApisNotAllowed (erreur 403)

« Can't write to DataStore from Studio because API access is not enabled. » Publie le jeu, puis active Enable Studio Access to API Services dans File > Experience Settings > Security, dans la copie de test.

DataStore request was added to queue

Le serveur envoie des requêtes plus vite que son budget, ou écrit la même clé trop souvent, en général en sauvegardant à chaque changement ou dans une boucle. Quand une file contient 30 requêtes, les nouvelles échouent avec les erreurs 301 à 306. Garde les données en mémoire et sauvegarde à intervalles réguliers.

CantStoreValue (erreur 104), ou un champ revient à nil

La table contient quelque chose qu'un data store ne peut pas sauvegarder, comme une Instance, un Vector3 ou un Color3. Sauvegarde plutôt un nom, un identifiant ou de simples nombres, et reconstruis l'objet au chargement.

ValueTooLarge (erreur 105)

Une clé contient plus de 4 194 304 caractères de JSON. Mesure avec #HttpService:JSONEncode(data), retire ce que tu peux reconstruire, ou répartis les données sur quelques clés fixes.

Pas d'erreur, mais les données ne se sauvegardent pas

Cherche l'avertissement Could not load du module : après un chargement raté, il refuse de sauvegarder, c'est voulu. Sinon, la valeur a sans doute été changée dans un LocalScript, ce qui n'arrive jamais au serveur, ou un autre script sauvegarde la même clé.

Les données repartent à zéro chaque fois que je reviens

La clé change d'une session à l'autre (construite à partir de player.Name, ou STORE_NAME a été modifié), le chargement échoue et tu vois les valeurs par défaut, ou rien ne require le module, donc il ne tourne jamais. Vérifie l'Output et que Main require bien PlayerData.

Le faire avec RoCode

Si tu préfères ne pas tout câbler à la main, RoCode peut le construire dans le jeu que tu as ouvert. C'est un agent IA indépendant, qui n'est pas fait par Roblox, et qui travaille grâce à un plugin pour Roblox Studio : il écrit du Luau qui utilise DataStoreService comme n'importe quel script et crée les scripts dans ton Explorer. Il n'appelle jamais lui-même tes data stores, mais avec le plugin 3.9 ou plus récent, il peut appuyer sur Play pour un court test, où tes scripts tournent comme dans n'importe quel test.

Tu écris

Ajoute la sauvegarde à mon jeu : garde Coins, Level et Inventory dans un module PlayerData avec autosave et sauvegardes à l'arrêt, et affiche Coins dans les leaderstats que j'ai déjà.

RoCode fait
  • Peut chercher du code leaderstats et DataStore existant avec Search Scripts et Read Script, pour compléter ce que tu as au lieu d'ajouter un deuxième script de sauvegarde. Dans un grand jeu, nomme le script ou le dossier dans ton message.
  • Crée le ModuleScript et le Script qui le require avec Create Script, ou modifie ceux que tu as avec Edit Script
  • Lance Check Script sur chaque script qu'il a écrit : une vérification de compilation dans Studio avec une courte liste d'avertissements, pas une vérification de types ni un test en jeu
  • Envoie ses changements par lots, et chaque lot est un point d'annulation dans Studio

Tu actives toujours toi-même Studio Access to API Services dans ta copie de test : RoCode ne peut pas changer ce réglage. Avec le plugin 3.9 ou plus récent, son court test lit les erreurs, et avec le plugin 3.9.11 ou plus récent, il peut contrôler un personnage de test pour vérifier que le jeu marche, mais il ne vérifie que ce qu'il a choisi de tester, donc joue toi-même pour vérifier que Coins, Level et Inventory se sauvegardent et se chargent. Si une sauvegarde échoue pendant ton test, Check Output peut lire les lignes Server du test que tu as lancé. La sauvegarde vient en général une fois la boucle principale en place ; créer un jeu Roblox avec l'IA un système à la fois présente cet ordre. Comment RoCode se connecte à Studio.

Questions fréquentes

Comment activer le DataStore dans Roblox Studio ?

Publie le jeu, ouvre File > Experience Settings > Security, active Enable Studio Access to API Services et clique sur Save. Fais-le dans un jeu de test séparé, parce que Studio utilise alors les mêmes data stores que les serveurs publiés de ce jeu.

Roblox sauvegarde-t-il automatiquement les données des joueurs ?

Non. Rien d'un joueur ne dure au-delà de la session, sauf si un script serveur le sauvegarde avec DataStoreService, et ça inclut leaderstats.

Faut-il utiliser ProfileStore ou DataStoreService directement ?

ProfileStore est lui aussi construit sur les data stores, donc la question est de savoir si tu veux qu'on écrive et maintienne le verrouillage de session pour toi. Pour des échanges, des objets payants ou des téléportations fréquentes, le verrouillage vaut le coup, depuis une bibliothèque ou l'exemple de référence de Roblox. Pour un jeu plus petit, un module comme celui-ci est plus facile à lire et à modifier.

Comment réinitialiser ou supprimer les données d'un joueur ?

Dans Data Stores Manager, trouve la clé et choisis Mark for Deletion, que tu peux annuler pendant une période d'attente, ou appelle RemoveAsync sur la clé depuis un script serveur. Fais-le pendant que le joueur est hors ligne, sinon la sauvegarde suivante de son serveur réécrit les données. Dans la copie de test, changer STORE_NAME fait repartir tout le monde de zéro ; ne fais jamais ça dans un jeu publié.

Sources et lectures

Comment le code a été vérifié : chaque script de cette page passe le vérificateur de types strict de Luau avec les définitions de l'API Roblox (luau-lsp, 12 novembre 2026). Une vérification de types repère les API mal écrites et les mauvais types, pas la logique du jeu : teste dans Studio avant de publier.

Essaie RoCode sur ton propre jeu.

Des crédits gratuits chaque jour, sans carte. Installe le plugin, décris la fonctionnalité et vérifie ce qui arrive dans Studio.