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
- Activer l'accès Studio
- Fonctionnement des data stores
- GetAsync vs UpdateAsync
- 1. Module PlayerData
- Fonctionnement du module
- 2. Utiliser les données
- 3. Prévenir le joueur
- 4. Tester dans Studio
- Pertes de données
- Verrouillage de session
- Limites
- Versions et copies
- Problèmes courants
- Avec RoCode
- Questions fréquentes
- 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.
- 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.
- Dans la copie de test, ouvre File > Experience Settings et va dans Security.
- 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
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.
| Type | Sauvegardé ? | Notes |
|---|---|---|
| Nombres, chaînes, booléens, buffers | Oui | Les chaînes doivent être en UTF-8 valide. Ne sauvegarde pas inf ni nan. |
| Tables | Oui | Si 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, Color3 | Non | La 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
| Méthode | Ce 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
nilannule 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.
- Dans l'Explorer, survole ServerScriptService, clique sur + et insère un ModuleScript. Renomme-le
PlayerDataet remplace son contenu par le code ci-dessous. - Un ModuleScript ne tourne que quand un script le require. Insère un Script dans ServerScriptService nommé
Mainavec cette ligne :local PlayerData = require(game:GetService("ServerScriptService").PlayerData). Les autres scripts serveur le require de la même façon. - Modifie
DEFAULTSet le typeDatapour qu'ils correspondent à ton jeu, en gardant chaque champ en nombre, chaîne, booléen ou table.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- 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
| Quand | Pourquoi |
|---|---|
| Toutes les 180 secondes tant que le joueur est sur le serveur | Limite 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 :
| Appel | Ce 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.Loaded | Se 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.
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é.
- 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) - 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. - Appuie sur Stop. Terminer le test ferme le serveur, et le module te sauvegarde avant qu'il se ferme.
- 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.
- 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. - 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 passe | Résultat | Prévention |
|---|---|---|
| Un chargement échoue et le script sauvegarde quand même | Les valeurs par défaut écrasent la vraie progression : un effacement complet | Ne jamais sauvegarder un joueur dont le chargement a échoué |
Sauvegarder seulement dans PlayerRemoving | Un plantage ou un arrêt saute la sauvegarde | Une autosave, plus un BindToClose qui attend ses sauvegardes |
Pas de pcall ou pas de nouvelle tentative | Une seule requête ratée arrête le script ou perd la sauvegarde | Un pcall avec quelques nouvelles tentatives espacées |
| Sauvegarder à chaque changement | Les requêtes s'accumulent ; quand une file en contient 30, les nouvelles sont abandonnées | Garder les données en mémoire et sauvegarder à intervalles réguliers |
| Sauvegarder quelque chose qu'un data store ne peut pas contenir | La sauvegarde plante, ou la valeur revient à nil | Sauvegarder des nombres, des chaînes, des booléens et des tables de ces types |
| Changer la forme des données sans migration | Les anciennes sauvegardes se chargent dans les mauvais champs | Une version de schéma et une étape de migration |
| Deux scripts qui sauvegardent la même clé | Chaque sauvegarde écrase les champs de l'autre | Un seul module possède la clé |
| Deux serveurs qui ont le même joueur | Le serveur aux données plus anciennes sauvegarde en dernier et écrase une progression plus récente | Le 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.
| Option | Ce que c'est | Bon à savoir |
|---|---|---|
| Le module de ce guide | Chargement, mise en mémoire, nouvelles tentatives, autosave, sauvegardes à l'arrêt et versions de schéma, sans verrouillage | Assez court pour être lu en entier et modifié |
| L'exemple de Roblox pour les données des joueurs et les achats | Du 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'achat | Roblox 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 |
| ProfileStore | Un module communautaire gratuit et open source, le successeur de ProfileService, construit autour du verrouillage de session et de l'autosave | Pas 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.
| Type de requête | Data stores standard | Ordered data stores |
|---|---|---|
Lecture : GetAsync, la lecture dans UpdateAsync | 60 + 40 × joueurs | 60 + 40 × joueurs |
Écriture : SetAsync, IncrementAsync, l'écriture dans UpdateAsync | 60 + 40 × joueurs | 30 + 5 × joueurs |
Liste : ListKeysAsync, ou GetSortedAsync pour les stores ordonnés | 5 + 2 × joueurs | 5 + 2 × joueurs |
Suppression : RemoveAsync | 60 + 40 × joueurs | 30 + 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.
| Limite | Valeur |
|---|---|
| Nom du data store, nom de clé, scope | 50 caractères chacun |
| Valeur sauvegardée dans une clé | 4 194 304 caractères, mesurés en JSON |
| Lectures d'une clé, tous serveurs confondus | 25 Mo par minute |
| Écritures dans une clé, tous serveurs confondus | 4 Mo par minute, chaque requête arrondie au Ko supérieur |
| Requêtes en attente | 30 par file ; au-delà, les requêtes échouent avec les erreurs 301 à 306 |
| Stockage pour tout le jeu | 500 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.
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à.
- 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
- Roblox Creator Docs : Data stores (en anglais). l'accès depuis Studio, GetAsync, SetAsync, UpdateAsync, set contre update
- Roblox Creator Docs : Best practices for data stores (en anglais). une clé par joueur, la mise en mémoire, les nouvelles tentatives avec délai croissant, les modules tiers
- Roblox Creator Docs : Data store error codes and limits (en anglais). les codes d'erreur, les limites de requêtes par serveur et par jeu, les limites de taille, de débit et de stockage
- Roblox Creator Docs : Versioning, listing and caching (en anglais). les versions horaires, les snapshots, le cache de 4 secondes, ce qui peut être sauvegardé
- Roblox Creator Docs : Implement player data and purchasing systems (en anglais). l'exemple de référence, le verrouillage de session, les chargements ratés, l'autosave toutes les 180 secondes
- Roblox Creator Docs : Data Stores Manager (en anglais). voir les clés, revenir à une version, supprimer des données
- Roblox Engine API : DataModel:BindToClose (en anglais). la fenêtre de 30 secondes à l'arrêt
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.