בקצרה
השתמשו ב-DataStoreService מתוך Script של שרת: טענו את נתוני השחקן דרך GetAsync כשהוא נכנס, החזיקו אותם בטבלה בזמן שהוא משחק, ושמרו דרך UpdateAsync לפי טיימר, ביציאה (PlayerRemoving) ובכיבוי השרת (game:BindToClose). עטפו כל קריאה ב-pcall ונסו שוב כמה פעמים קריאות שנכשלו.
- כדי לבדוק ב-Studio, פרסמו את הפלייס והפעילו את File > Experience Settings > Security > Enable Studio Access to API Services במשחק בדיקה נפרד: Studio משתמש באותם נתונים כמו השרתים החיים.
- אם נתוני השחקן לא נטענו, אף פעם אל תשמרו את השחקן הזה. שמירה של ערכי ברירת המחדל תדרוס את ההתקדמות האמיתית שלו.
- שמרו טבלה אחת לכל שחקן תחת מפתח אחד, למשל
User_12345, ושמרו לפי טיימר, לא בכל שינוי. - להחלפת פריטים או לפריטים בתשלום הוסיפו נעילת סשן, כדי ששני שרתים לא יוכלו לשמור את אותו שחקן.
בעמוד הזה
לפני שמתחילים: הפעילו גישת Studio בעותק בדיקה
משחק שרץ ב-Studio לא יכול לפנות למאגרי נתונים עד שתתירו את זה. להיתר יש מלכודת שהתיעוד של Roblox מזהיר עליה: Studio אז קורא וכותב לאותם מאגרי נתונים כמו המשחק החי, ולכן בדיקה שמאפסת את המטבעות שלכם ב-Studio מאפסת אותם גם במשחק החי, ובאג בקוד הבדיקה יכול לקלקל מפתחות של שחקנים אמיתיים.
- צרו עותק בדיקה. שמרו את הפלייס לקובץ, פתחו את העותק, בחרו File > Publish to Roblox As ולחצו על Create new game. אל תוסיפו אותו כפלייס בתוך המשחק החי: כל הפלייסים של משחק אחד חולקים את אותם מאגרי נתונים.
- בעותק הבדיקה פתחו File > Experience Settings ועברו ל-Security.
- הפעילו את Enable Studio Access to API Services ולחצו על Save.
קריאות למאגרי נתונים עובדות רק ב-Script של שרת; LocalScript שינסה יקבל שגיאה, ולכן לקוחות לא יכולים לכתוב נתונים שמורים. כשכפתור צריך לשנות אותם, הלקוח מבקש מהשרת דרך RemoteEvent, והשרת מחליט (ראו את המדריך ל-RemoteEvents, באנגלית).
איך מאגרי נתונים שומרים נתוני שחקנים
מאגר נתונים (data store) הוא אוסף בעל שם של מפתחות וערכים בשרתים של Roblox, משותף לכל השרתים ולכל הפלייסים של המשחק שלכם. DataStoreService:GetDataStore("PlayerData") מחזיר מאגר אחד כזה.
ההמלצות של Roblox מסתכמות בכלל מאגר אחד לנתוני שחקנים, מפתח אחד לכל שחקן, טבלה אחת בכל מפתח. הרכיבו את המפתח מה-UserId של השחקן, למשל User_12345, ואף פעם לא מהשם, שהוא יכול לשנות. התבנית הקבועה User_{UserId} גם מאפשרת לטיפול האוטומטי של Roblox בזכות להישכח למצוא את נתוני השחקן, אם תגדירו אותו.
| סוג | נשמר? | הערות |
|---|---|---|
| מספרים, מחרוזות, בוליאנים, באפרים | כן | מחרוזות חייבות להיות UTF-8 תקין. אל תשמרו inf או nan. |
| טבלאות | כן | אם גם כל מה שבתוכן אפשר לשמור. טבלה שהמפתחות המספריים שלה לא מתחילים ב-1 (ולכן האורך שלה 0) חוזרת עם המפתחות האלה כמחרוזות. |
Instance, Vector3, CFrame, Color3 | לא | השמירה זורקת שגיאה או כותבת nil. שמרו את שם הפריט או את המיקום כשלושה מספרים. |
כל בקשה היא קריאת רשת שעלולה להיכשל, לוקחת זמן וצורכת תקציב לדקה. לכן מערכות שמירה אמינות קוראות את הנתונים פעם אחת כשהשחקן נכנס, מחזיקות אותם בטבלה בשרת בזמן שהוא משחק, ומדי פעם כותבות אותם בחזרה.
GetAsync, SetAsync או UpdateAsync: מה לבחור
| שיטה | מה היא עושה | בשביל מה |
|---|---|---|
GetAsync(key) | קוראת ערך. התוצאה נשמרת במטמון בשרת הזה ל-4 שניות. | טעינת נתוני שחקן |
SetAsync(key, value) | דורסת ערך בלי לקרוא אותו. כתיבה אחת. | מפתח חדש או ערך שלא תלוי בקודם |
UpdateAsync(key, callback) | קוראת את הערך האחרון, מעבירה אותו לפונקציה שלכם וכותבת את מה שהיא מחזירה. קריאה אחת וכתיבה אחת. | שמירת נתוני שחקן וכל מפתח שכמה שרתים עשויים לכתוב |
IncrementAsync(key, delta) | מוסיפה מספר שלם למספר שלם שמור. | מונים |
RemoveAsync(key) | מוחקת מפתח ומחזירה את הערך הישן. אפשר עדיין לפרט ולקרוא גרסאות קודמות. | מחיקת נתוני שחקן |
SetAsync כותבת בעיוורון: אם שני שרתים שומרים את אותו מפתח כמעט באותו זמן, הכתיבה האחרונה מנצחת, לא משנה מה יש בה. UpdateAsync קוראת קודם את הערך הנוכחי, ואם שרת אחר כותב בינתיים, Roblox מריצה שוב את הפונקציה שלכם עם הערך החדש. Roblox ממליצה עליה תמיד כשהכתיבה תלויה בערך הנוכחי או שכמה שרתים עשויים לכתוב את המפתח, וזה בדיוק המצב עם נתוני שחקן. לפונקציה יש שלושה כללים:
- אסור לה לוותר על הביצוע (yield): בלי
task.wait()ובלי קריאות אחרות למאגרים בתוכה. - היא יכולה לרוץ יותר מפעם אחת, ולכן היא צריכה רק לחשב את הערך החדש ואף פעם לא לתת פריטים או להפעיל אירועים.
- החזרת
nilמבטלת את הכתיבה. המודול משתמש בזה כדי לא לדרוס נתונים שנשמרו על ידי גרסה חדשה יותר של המשחק.
שלב 1: צרו את המודול PlayerData
ה-ModuleScript הזה הוא הקוד היחיד שמדבר עם מאגר הנתונים. הוא טוען את נתוני השחקן בכניסה, מחזיק אותם בזיכרון, שומר כל 180 שניות, ביציאה ובכיבוי השרת, ומסרב לשמור את מי שהנתונים שלו לא נטענו.
- ב-Explorer רחפו מעל ServerScriptService, לחצו על + והכניסו ModuleScript. שנו את השם שלו ל-
PlayerDataוהחליפו את התוכן בקוד שלמטה. - ModuleScript רץ רק כשסקריפט כלשהו טוען אותו (require). הכניסו ל-ServerScriptService Script בשם
Mainעם השורה הזו:local PlayerData = require(game:GetService("ServerScriptService").PlayerData). סקריפטי שרת אחרים טוענים אותו באותה דרך. - שנו את
DEFAULTSואת הטיפוסDataלמשחק שלכם, ושמרו שכל שדה יהיה מספר, מחרוזת, בוליאני או טבלה.
ServerScriptService
PlayerData ModuleScript new
Main Script new
StarterPlayer
StarterPlayerScripts
DataWarning LocalScript new
-- PlayerData: טוען את נתוני השחקן בכניסה, מחזיק אותם בזיכרון
-- ושומר לפי טיימר, ביציאה ובכיבוי השרת.
-- סקריפטי שרת אחרים קוראים ומשנים אותם דרך 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 -- העלו כשצורת הנתונים משתנה, והוסיפו שלב ב-migrate()
local AUTOSAVE_SECONDS = 180
-- ב-Studio קריאה שנכשלה מוותרת מיד, ולכן בדיקה בלי גישה למאגר רצה מהר
local MAX_ATTEMPTS = if RunService:IsStudio() then 1 else 4
local FIRST_RETRY_SECONDS = 1 -- מוכפל אחרי כל כישלון: 1, 2, 4
export type Data = {
SchemaVersion: number,
Coins: number,
Level: number,
Inventory: { string },
}
-- עם מה מתחיל שחקן חדש לגמרי
local DEFAULTS: { [string]: any } = {
Coins = 0,
Level = 1,
Inventory = {},
}
type Session = {
key: string,
userId: number,
data: Data,
canSave: boolean, -- false אם הטעינה נכשלה: נתוני ברירת מחדל לא אמורים להחליף התקדמות אמיתית
}
-- נקרא בתוך כל pcall שלמטה, ולכן פלייס שעוד לא פורסם
-- (בלי גישה למאגר) עדיין טוען שחקנים עם נתוני ברירת מחדל
local function store(): DataStore
return DataStoreService:GetDataStore(STORE_NAME)
end
local sessions: { [Player]: Session } = {}
local pendingSaves: { [string]: number } = {} -- שמירות שעדיין רצות, לפי מפתחות
local loadedEvent = Instance.new("BindableEvent")
local PlayerData = {}
-- נורה עם השחקן כשהנתונים שלו מוכנים. את הטבלה קחו דרך PlayerData.Get(player):
-- טבלה שנשלחת דרך BindableEvent מגיעה כעותק, ושינוי שלה לא ישנה כלום.
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) -- עותק טרי, כדי ששחקנים אף פעם לא יחלקו טבלת Inventory אחת
data.SchemaVersion = SCHEMA_VERSION
return data
end
-- מביא נתונים שמורים לסכמה הנוכחית. מחזיר nil אם אי אפשר להשתמש בהם בבטחה.
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 -- נשמר על ידי גרסה חדשה יותר של המשחק: כאן לא טוענים ולא דורסים
end
-- שלב אחד לכל שינוי סכמה, מהישנים לחדשים
if version < 2 then
-- דוגמה: בגרסה 1 המטבע נקרא Gold. מעתיקים אותו רק אם אין Coins,
-- כדי שנתונים ישנים שבהם כבר יש Coins, אבל אין SchemaVersion, ישמרו על הערך.
if saved.Coins == nil then
saved.Coins = saved.Gold
end
saved.Gold = nil
end
-- מוסיפים שדות שהופיעו אחרי השמירה האחרונה של השחקן, ומחליפים ערכים מסוג שגוי
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
-- מריץ קריאה למאגר בתוך pcall. בכישלון מחכה ומנסה שוב, ובכל פעם מכפיל
-- את ההמתנה ומוסיף קצת אקראיות, כדי שהשרתים לא ינסו שוב כולם יחד.
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 מבטלת את הכתיבה
end
-- כותבים את כל הטבלה הנוכחית עם סימון ה-UserId של השחקן
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()
-- מתחילים ברגע אקראי במרווח, כדי שהשרתים לא ישמרו כולם יחד
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
-- אם השחקן בדיוק יצא מהשרת הזה וחזר, קודם נותנים לשמירה האחרונה להסתיים
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 -- יצא בזמן הטעינה: שום דבר לא השתנה, אין מה לשמור
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) -- GUI יכול לקרוא את זה ולהזהיר את השחקן
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 -- עוצר את לולאת השמירה האוטומטית, וקריאה חוזרת לא עושה כלום
save(session)
end
-- טבלת הנתונים החיה של השחקן, או nil עד שהיא נטענה. שנו אותה רק מסקריפטי שרת.
function PlayerData.Get(player: Player): Data?
local session = sessions[player]
return if session then session.data else nil
end
-- True כשנתוני השחקן נטענו ויישמרו. בדקו לפני כל מכירה.
function PlayerData.CanSave(player: Player): boolean
local session = sessions[player]
return session ~= nil and session.canSave
end
-- שומר עכשיו, בלי לחכות לטיימר, לרגעים חשובים כמו קנייה.
-- מוותר על הביצוע ומחזיר true כשהשמירה עברה.
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) -- שחקנים שנכנסו לפני הטעינה הראשונה של המודול הזה
end
game:BindToClose(function()
-- השרת נותן לפונקציות האלה 30 שניות, ולכן שומרים את כולם בבת אחת
for player in sessions do
task.spawn(endSession, player)
end
-- אחר כך מחכים לכל השמירות שעדיין רצות, כולל אלה שהתחילו ב-PlayerRemoving
while next(pendingSaves) do
task.wait()
end
end)
return PlayerData
אחרי שהמשחק יצא, אל תשנו את STORE_NAME ואת תבנית המפתח User_. שינוי של כל אחד מהם יפנה את המודול למפתחות ריקים, וכל שחקן יתחיל מחדש מערכי ברירת המחדל.
איך המודול שומר על הנתונים
ערכי ברירת מחדל וגרסת סכמה
שחקן חדש מקבל עותק טרי של DEFAULTS. זה חייב להיות דווקא עותק: אם כל השחקנים היו חולקים טבלת Inventory אחת, פריט שנוסף לאחד היה מופיע אצל כולם.
כל טבלה שמורה נושאת SchemaVersion. הוספת שדה לא דורשת גרסה חדשה, כי migrate ממלא שדות חסרים מערכי ברירת המחדל. שינוי שם או מבנה כן דורש: העלו את SCHEMA_VERSION והוסיפו שלב, כמו בדוגמה שמשנה את השם Gold ל-Coins (במשחק חדש מחקו אותה והתחילו מ-1). נתונים עם גרסה גבוהה מזו של השרת הגיעו מגרסה חדשה יותר שעדיין נפרסת, ולכן שרתים ישנים לא נוגעים בהם.
טעינה שנכשלה אף פעם לא נשמרת
הכלל הזה מגן מפני מחיקה מלאה. אם כל ניסיונות הטעינה נכשלו, השחקן משחק על נתוני ברירת מחדל, אבל canSave שווה false, ולכן הערכים האלה אף פעם לא ידרסו את ההתקדמות האמיתית שלו. המודול גם קובע את ה-Attribute בשם DataLoaded ל-false, ושלב 3 משתמש בו כדי להודיע לשחקן. הדוגמה הרשמית של Roblox מטפלת בטעינות שנכשלו באותה דרך ומציעה את זה במקום להעיף את השחקן; אם אתם מעדיפים להעיף, קראו ל-player:Kick() עם הודעה במקום שבו המודול מדפיס אזהרה.
ניסיונות חוזרים עם הפסקה שגדלה
withRetries עוטף כל קריאה ב-pcall. אחרי כישלון הוא מחכה 1, ואז 2, ואז 4 שניות, ובכל פעם עוד עד חצי מהזמן הזה באקראי, ונעצר אחרי ארבעה ניסיונות (ב-Studio אחרי אחד, כדי שפלייס בלי גישה למאגר יעלה מיד). האקראיות מפזרת את הניסיונות החוזרים של הרבה שרתים אחרי תקלה, וההגבלה שומרת את ההמתנה בתוך בערך 10 שניות, בתוך 30 השניות שהשרת מקבל לכיבוי. מכיוון שכל שמירה כותבת את כל הטבלה החיה דרך UpdateAsync, ניסיון חוזר שהסתיים באיחור לא יכול להחזיר נתונים ישנים.
מתי המודול שומר
| מתי | למה |
|---|---|
| כל 180 שניות, בזמן שהשחקן בשרת | מגביל את האובדן בקריסה. השמירה הראשונה נופלת ברגע אקראי במרווח, כדי שהשרתים לא ישמרו כולם יחד. גם הדוגמה הרשמית של Roblox משתמשת ב-180 שניות. |
כשהשחקן יוצא (PlayerRemoving) | השמירה הסופית הרגילה. הסשן נמחק קודם, ולכן השמירה האוטומטית נעצרת. |
כשהשרת נכבה (game:BindToClose) | כל מי שעדיין בשרת נשמר בבת אחת, והפונקציה מחכה לכל שמירה שרצה. Roblox נותנת לה 30 שניות. |
לפי בקשה, דרך PlayerData.SaveNow(player) | אחרי משהו שאסור לאבד, למשל קנייה. |
אם שחקן נכנס שוב לאותו שרת בזמן שהשמירה הסופית שלו עדיין רצה, הטעינה החדשה מחכה לסוף השמירה הזו, ולכן לא יכולה לקרוא את הערך הישן.
שלב 2: קראו ושנו את הנתונים מסקריפטים אחרים
כל סקריפטי השרת שטוענים את המודול עובדים עם אותן טבלאות:
| קריאה | מה היא עושה |
|---|---|
PlayerData.Get(player) | טבלת הנתונים החיה של השחקן, או nil עד שהיא נטענה. שנו שדות ישירות, למשל data.Coins += 10, והשמירה הבאה תקלוט את זה. |
PlayerData.Loaded | נורה עם השחקן כשהנתונים שלו מוכנים, גם אחרי טעינה שנכשלה. מעביר רק את השחקן, כי טבלה שנשלחת דרך BindableEvent מגיעה כעותק. |
PlayerData.CanSave(player) | false אם הטעינה נכשלה. בדקו לפני כל מכירה: קנייה שאי אפשר לשמור תיעלם כשהשחקן ייצא. |
PlayerData.SaveNow(player) | שומר מיד ומחזיר true אם הצליח. מוותר על הביצוע. |
המודול הוא המקום היחיד שבו חיים הנתונים השמורים, ו-leaderstats הוא רק תצוגה: בנו אותו כמו במדריך לטבלת מובילים, מלאו אותו מ-PlayerData.Get(player) ב-handler של Loaded, ועדכנו את שניהם כשערך משתנה. אף פעם אל תקראו ערכים שמורים בחזרה מ-leaderstats, ואף פעם אל תתנו לסקריפט שני לשמור את אותו מפתח.
סקריפט שטען את המודול אחרי ששחקנים נכנסו מפספס בשבילם את Loaded. חברו את ה-handler, ואז עברו גם בלולאה על Players:GetPlayers() וטפלו בכל מי ש-PlayerData.Get(player) כבר מחזיר לו טבלה.
מחליפים סקריפט שמירה ישן, למשל מהמדריך לטבלת מובילים? הערכים שלו נשארים במאגר ובמפתח שלו, ולכן המודול הזה יתחיל את כולם מערכי ברירת מחדל. לפני ההשקה, או שתפנו את STORE_NAME ואת הקידומת User_ לישנים (migrate מתייחס לנתונים בלי SchemaVersion כגרסה 1 וממלא שדות חסרים), או שתעבירו את הערכים הישנים, ואז תמחקו את הסקריפט הישן.
לקוחות אף פעם לא משנים את הנתונים האלה ישירות. כפתור בחנות מפעיל RemoteEvent; השרת בודק את CanSave, משווה את המחיר ל-Coins של השחקן, משנה את הטבלה וקורא ל-SaveNow. המדריך ל-GUI של חנות בונה קנייה כזו בצד השרת.
דוגמה מוכנה להוספת שדות יש במדריך לסימולטור קליקים: הוא מוסיף את PowerLevel ואת Rebirths ל-DEFAULTS ולטיפוס Data, ואז משנה אותם בטבלה ש-PlayerData.Get מחזיר. migrate נותן את השדות החדשים לשחקנים עם שמירות ישנות.
שלב 3: הודיעו לשחקן שהנתונים שלו לא נטענו
שחקן שהנתונים שלו לא נטענו צריך לדעת שהסשן הזה לא יישמר, כדי שייכנס מחדש ולא ישחק לשווא. ה-LocalScript הזה עוקב אחרי ה-Attribute בשם DataLoaded ומציג באנר כשהוא שווה 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
-- השרת קובע את DataLoaded פעם אחת, אחרי הניסיון לטעון את הנתונים של השחקן הזה
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()
שלב 4: בדקו את השמירה ב-Studio
עשו את זה בעותק הבדיקה עם גישת Studio מופעלת.
- תנו לעצמכם משהו לשמור. מתחת לשורת ה-require ב-
Mainהוסיפו:PlayerData.Loaded:Connect(function(player) local data = PlayerData.Get(player) if data then data.Coins += 100 print(player.Name, data.Coins) end end) - לחצו על Play. חלון ה-Output (בתפריט Window או בלשונית Script) יציג את השם שלכם ו-100 (בהרצה הראשונה), בלי האזהרה
Could not load. - לחצו על Stop. סיום הבדיקה סוגר את השרת, והמודול שומר אתכם לפני הסגירה.
- לחצו שוב על Play. ה-Output אמור להציג 200, 100 יותר מהפעם הקודמת. אם הוא מציג שוב את אותו מספר, השמירה לא עברה: קראו את האזהרות שמעליו.
- בדקו את המסלול עם השגיאה. כבו את גישת Studio ולחצו על Play. אחרי כמה שניות של ניסיונות חוזרים ה-Output יציג
Could not load User_...ו-100, והבאנר משלב 3 יופיע. עצרו את הבדיקה, הפעילו שוב את הגישה ולחצו על Play: ה-Output יציג 300, ה-200 השמורים שלכם ועוד 100, כי הסשן שנכשל אף פעם לא דרס את הנתונים שלכם. - מחקו את שורת הבדיקה מ-
Main.
למה נתוני שחקנים הולכים לאיבוד
אלה הדרכים הרגילות שבהן מערכת שמירה מאבדת התקדמות. המודול סוגר בקוד את ארבע השורות הראשונות ואת השורה על הסכמה; השאר תלויות במה ואיך אתם שומרים, ולאחרונה צריך נעילת סשן.
| מה קורה | תוצאה | איך למנוע |
|---|---|---|
| הטעינה נכשלה, והסקריפט שומר בכל זאת | ערכי ברירת המחדל דורסים התקדמות אמיתית: מחיקה מלאה | אף פעם לא לשמור שחקן שהטעינה שלו נכשלה |
שמירה רק ב-PlayerRemoving | קריסה או כיבוי של השרת מדלגים על השמירה | שמירה אוטומטית ועוד BindToClose שמחכה לשמירות שלו |
אין pcall או אין ניסיון חוזר | בקשה אחת שנכשלה עוצרת את הסקריפט או מאבדת שמירה | pcall עם כמה ניסיונות חוזרים מפוזרים בזמן |
| שמירה בכל שינוי | הבקשות נכנסות לתור; כשיש בתור 30, חדשות נזרקות | להחזיק נתונים בזיכרון ולשמור לפי טיימר |
| שמירה של מה שהמאגר לא יודע לשמור | השמירה זורקת שגיאה, או שהערך חוזר nil | לשמור מספרים, מחרוזות, בוליאנים וטבלאות שלהם |
| שינוי צורת הנתונים בלי מיגרציה | שמירות ישנות נטענות לשדות הלא נכונים | גרסת סכמה ושלב מיגרציה |
| שני סקריפטים שומרים את אותו מפתח | כל שמירה דורסת את השדות של השני | מודול אחד הוא הבעלים של המפתח |
| שני שרתים מחזיקים את אותו שחקן | שרת עם נתונים ישנים שומר אחרון ודורס את ההתקדמות החדשה | נעילת סשן |
נעילת סשן, "lock lost" ו-ProfileStore
שחקן מחובר לשרת אחד בכל פעם, אבל השמירה הסופית של השרת הישן עדיין יכולה לרוץ כשהוא נכנס לחדש: ניסיון חוזר איטי, טלפורט או כניסה מחדש מהירה. אם השרת החדש טוען את הנתונים ראשון, יהיו לו נתונים ישנים, וינצח השרת ששומר אחרון. התיעוד של Roblox מציין שבמשחקים עם החלפות הפער הזה הוא סיבה נפוצה לשכפול פריטים.
נעילת סשן סוגרת את הפער הזה. כששרת טוען את המפתח של שחקן, הוא כותב באותה קריאת UpdateAsync את מזהה הנעילה שלו במטא-נתונים של המפתח. כל שרת אחר שמוצא נעילה שלא פגה ושלא הוא הציב לא יטען ולא ישמור את המפתח הזה. הבעלים מחדש את הנעילה בכל שמירה אוטומטית ומשחרר אותה בשמירה הסופית; אם הוא מפסיק לחדש אותה, הנעילה פגה, ושרת אחר יכול לקחת אותה.
מה זה "lock lost"
במערכת עם נעילת סשן, שרת איבד את הנעילה כששרת אחר הוא עכשיו הבעלים של מפתח השחקן, כי הנעילה פגה או נלקחה. העותק שלו עלול להיות ישן, ולכן הוא צריך להפסיק לשמור את השחקן הזה; התגובה הרגילה: להעיף אותו עם הודעה, כדי שיתחבר מחדש. אם ראיתם "lock lost" כשחקן, זו הודעה של מערכת השמירה של אותו משחק עצמו, ורק המפתחים שלו יכולים להסביר אותה.
אתם צריכים אותה?
המודול מהמדריך הזה לא נועל סשנים. בלי נעילה, המקרה הגרוע ביותר האמיתי הוא כזה: במרוץ נדיר שחקן מאבד את מה שהרוויח בשרת הישן אחרי השמירה המוצלחת האחרונה שלו. הוסיפו נעילה כששכפול או אובדן עולים לשחקנים במשהו אמיתי: החלפות, developer products, פריטים נדירים או טלפורטים תכופים.
| אפשרות | מה זה | מה כדאי לדעת |
|---|---|---|
| המודול מהמדריך הזה | טעינה, מטמון בזיכרון, ניסיונות חוזרים, שמירה אוטומטית, שמירה בכיבוי וגרסאות סכמה, בלי נעילה | קצר מספיק כדי לקרוא אותו כולו ולשנות |
| הדוגמה של Roblox לנתוני שחקנים ולרכישות | קוד רשמי של Roblox עם נעילת סשן, ניסיונות חוזרים לפי סדר לכל מפתח וטיפול בקבלות רכישה | Roblox אומרת שהוא לא נבחן לאורך זמן במשחק פופולרי ושאין להשתמש בו כמו שהוא בלי בדיקות נרחבות |
| ProfileStore | מודול קהילתי חינמי בקוד פתוח, היורש של ProfileService, שבנוי סביב נעילת סשן ושמירה אוטומטית | לא של Roblox. מעבר של משחק קיים אליו דורש מיגרציה של נתונים שכבר נשמרו |
לכל מודול של צד שלישי Roblox ממליצה לבדוק מי הבעלים שלו, אם הוא מתוחזק ואיך תגיעו לנתונים שלכם בלעדיו. אותו תיעוד מכנה את DataStore2 ספרייה מיושנת שמשחקים חדשים לא כדאי שישתמשו בה.
מגבלות של מאגרי נתונים
אלה המגבלות מהתיעוד של Roblox נכון ל-30 בספטמבר 2026. Roblox משנה אותן, ולכן בדקו את עמוד קודי השגיאות והמגבלות (באנגלית) לפני שאתם סומכים על מספר מדויק.
| סוג בקשה | מאגרים רגילים | מאגרים ממוינים |
|---|---|---|
קריאה: GetAsync, קריאה ב-UpdateAsync | 60 + 40 × שחקנים | 60 + 40 × שחקנים |
כתיבה: SetAsync, IncrementAsync, כתיבה ב-UpdateAsync | 60 + 40 × שחקנים | 30 + 5 × שחקנים |
רשימה: ListKeysAsync או GetSortedAsync למאגרים ממוינים | 5 + 2 × שחקנים | 5 + 2 × שחקנים |
מחיקה: RemoveAsync | 60 + 40 × שחקנים | 30 + 5 × שחקנים |
עם 20 שחקנים שרת יכול לבצע 860 כתיבות רגילות בדקה; השמירה האוטומטית של המודול הזה צורכת בערך 7 מהן, ועוד אחת לכל שחקן שיצא. את התקציב מכלה שמירה בכל מטבע שנאסף. תקציב שני חל על כל המשחק ומתחלק עם Open Cloud: 300 קריאות בדקה ועוד 40 לכל שחקן מחובר, ו-300 כתיבות ועוד 20 לכל שחקן.
| מגבלה | ערך |
|---|---|
| שם המאגר, שם המפתח, scope | 50 תווים כל אחד |
| ערך במפתח אחד | 4,194,304 תווים בפורמט JSON |
| קריאה של מפתח אחד מכל השרתים | 25 MB בדקה |
| כתיבה למפתח אחד מכל השרתים | 4 MB בדקה, כל בקשה מעוגלת למעלה ל-KB הבא |
| בקשות ממתינות | 30 לתור; מעבר לזה בקשות נכשלות עם שגיאות 301-306 |
| אחסון לכל המשחק | 500 MB ועוד 1 MB לכל משתמש בכל הזמנים |
את גודל נתוני השחקן מדדו דרך #HttpService:JSONEncode(data), ואת התקציב שנשאר לשרת חי בדקו דרך DataStoreService:GetRequestBudgetForRequestType(Enum.DataStoreRequestType.StandardWrite). קריאות GetAsync שהמטמון של 4 השניות ענה עליהן לא נספרות. למצב Run ב-Studio יש מגבלות משלו, אולי נמוכות יותר, ולכן לבדיקת מגבלות בקשות Roblox ממליצה על Team Create.
גרסאות וגיבויים
מאגרי נתונים רגילים שומרים היסטוריה בשבילכם. הכתיבה הראשונה למפתח בכל שעה לפי UTC נשמרת כגרסה, וכתיבות נוספות באותה שעה דורסות זו את זו. גרסה ישנה פגה 30 יום אחרי שכתיבה חדשה יותר החליפה אותה; האחרונה אף פעם לא פגה. מאגרים ממוינים לא שומרים גרסאות.
כדי להחזיר אחורה שחקן אחד, פתחו את Data Stores Manager (Creations, המשחק שלכם, Configure > Data Stores Manager), בחרו את המפתח שלו, בחרו גרסה מוקדמת יותר ולחצו על Revert; לזה צריך הרשאת Edit. עשו את זה כשהשחקן לא מחובר, אחרת השרת עם הסשן שלו ישמור את העותק שלו מעל ההחזרה. מתוך סקריפט שרת, ListVersionsAsync ו-GetVersionAsync מוצאים וקוראים גרסה ישנה, שאותה אתם כותבים אחר כך בחזרה כערך הנוכחי.
לפני פרסום עדכון שמשנה את דרך שמירת הנתונים, Roblox ממליצה לצלם snapshot דרך Open Cloud Snapshot Data Stores API (אחד ביום לכל משחק). בלעדיו, שמירה שגויה ב-3:30 UTC תדרוס את כל מה שנכתב למפתח הזה מ-3:00, כי היא נופלת לאותה גרסה שעתית.
שגיאות נפוצות ופתרונות
שגיאות של מאגרי נתונים מופיעות בחלון ה-Output של Studio, והמודול מדפיס אזהרה עם טקסט השגיאה של Roblox בכל ניסיון שנכשל. המדריך לשגיאות בסקריפטים מסביר איך קוראים את ה-Output באופן כללי.
StudioAccessToApisNotAllowed (שגיאה 403)
"Can't write to DataStore from Studio because API access is not enabled." פרסמו את הפלייס, ואז הפעילו את Enable Studio Access to API Services ב-File > Experience Settings > Security, בעותק הבדיקה.
DataStore request was added to queue
השרת שולח בקשות מהר יותר ממה שהתקציב מאפשר, או כותב יותר מדי לאותו מפתח, בדרך כלל בגלל שמירה בכל שינוי או בלולאה. כשבתור יש 30 בקשות, חדשות נכשלות עם שגיאות 301-306. החזיקו נתונים בזיכרון ושמרו לפי טיימר.
CantStoreValue (שגיאה 104), או ששדה חוזר nil
בטבלה יש משהו שהמאגר לא יודע לשמור, למשל Instance, Vector3 או Color3. שמרו במקום זה שם, ID או מספרים פשוטים, ושחזרו את האובייקט בטעינה.
ValueTooLarge (שגיאה 105)
מפתח אחד מחזיק יותר מ-4,194,304 תווי JSON. מדדו דרך #HttpService:JSONEncode(data), הסירו את מה שאפשר לשחזר, או חלקו את הנתונים לכמה מפתחות קבועים.
אין שגיאות, אבל הנתונים לא נשמרים
חפשו את האזהרה של המודול Could not load: אחרי טעינה שנכשלה הוא מסרב לשמור בכוונה. אחרת, הערך כנראה שונה ב-LocalScript, וזה אף פעם לא מגיע לשרת, או שסקריפט אחר שומר את אותו מפתח.
הנתונים מתאפסים בכל כניסה מחדש
המפתח משתנה בין סשנים (נבנה מ-player.Name, או ששיניתם את STORE_NAME), הטעינה נכשלת ואתם רואים ערכי ברירת מחדל, או שאף אחד לא טוען את המודול, והוא בכלל לא רץ. בדקו את ה-Output ושה-Main טוען את PlayerData.
בנו את זה עם RoCode
אם לא בא לכם לבנות את זה ביד, RoCode יכול לעשות את זה ישירות בפלייס שפתוח אצלכם. זה סוכן AI עצמאי, לא של Roblox, שעובד דרך פלאגין ל-Roblox Studio: הוא כותב Luau שמשתמש ב-DataStoreService כמו כל סקריפט, ויוצר סקריפטים ב-Explorer שלכם. הוא עצמו אף פעם לא פונה למאגרי הנתונים שלכם, אבל עם פלאגין 3.9 ומעלה הוא יכול ללחוץ על Play לבדיקת משחק קצרה, שבה הסקריפטים שלכם רצים כמו בכל בדיקה.
תוסיף שמירה למשחק שלי: תשמור Coins, Level ו-Inventory במודול PlayerData עם שמירה אוטומטית ושמירה בכיבוי השרת, ותציג את ה-Coins ב-leaderstats שכבר יש לי.
- יכול לחפש leaderstats וקוד DataStore קיימים עם Search Scripts ו-Read Script, כדי להרחיב את מה שיש לכם ולא להוסיף סקריפט שמירה שני. בפלייס גדול ציינו את הסקריפט או התיקייה בהודעה.
- יוצר ModuleScript ו-Script שטוען אותו עם Create Script, או משנה קיימים עם Edit Script
- מריץ Check Script לכל סקריפט שכתב: בדיקת קומפילציה בתוך Studio עם רשימה קצרה של אזהרות, לא בדיקת טיפוסים ולא הרצת בדיקה
- שולח את השינויים בקבוצות, וכל קבוצה היא נקודת ביטול (undo) ב-Studio
להפעיל את Studio Access to API Services בעותק הבדיקה תצטרכו בכל זאת בעצמכם: RoCode לא יכול לשנות את ההגדרה הזו. עם פלאגין 3.9 ומעלה בדיקת המשחק הקצרה שלו קוראת שגיאות, ועם פלאגין 3.9.11 ומעלה הוא יכול לשלוט בדמות בדיקה כדי לבדוק שהמשחק עובד, אבל הוא בודק רק את מה שהוא עצמו החליט לבדוק, אז שחקו בעצמכם וודאו ש-Coins, Level ו-Inventory נשמרים ונטענים. אם השמירה נכשלה בבדיקה שלכם, Check Output יכול לקרוא את שורות ה-Server מבדיקת המשחק שהרצתם. בדרך כלל מוסיפים שמירה כשלולאת המשחק העיקרית כבר עובדת; יצירת משחק Roblox עם AI, מערכת אחת בכל פעם מראה את הסדר הזה. איך RoCode מתחבר ל-Studio.
שאלות נפוצות
איך מפעילים DataStore ב-Roblox Studio?
פרסמו את הפלייס, פתחו File > Experience Settings > Security, הפעילו את Enable Studio Access to API Services ולחצו על Save. עשו את זה במשחק בדיקה נפרד, כי Studio אז משתמש באותם מאגרי נתונים כמו השרתים החיים של המשחק הזה.
Roblox שומרת נתוני שחקן אוטומטית?
לא. שום דבר על שחקן לא נשמר אחרי הסשן, אם סקריפט שרת לא שומר אותו דרך DataStoreService, וגם leaderstats לא.
מה לבחור: ProfileStore או DataStoreService ישירות?
גם ProfileStore בנוי על מאגרי נתונים, ולכן השאלה היא אם אתם רוצים שמישהו יכתוב ויתחזק את נעילת הסשן בשבילכם. להחלפות, לפריטים בתשלום או לטלפורטים תכופים, נעילה שווה את זה, מספרייה או מהדוגמה הרשמית של Roblox. למשחק קטן יותר מודול כמו זה פשוט יותר לקרוא ולשנות.
איך מאפסים או מוחקים נתוני שחקן?
ב-Data Stores Manager מצאו את המפתח ובחרו Mark for Deletion, שאפשר לבטל בתוך תקופת ההמתנה, או קראו ל-RemoveAsync על המפתח מסקריפט שרת. עשו את זה כשהשחקן לא מחובר, אחרת השמירה הבאה של השרת שלו תכתוב את הנתונים בחזרה. בעותק הבדיקה שינוי של STORE_NAME מתחיל את כולם מאפס; אף פעם אל תעשו את זה במשחק החי.
מקורות וקריאה נוספת
- Roblox Creator Docs: Data stores (באנגלית). גישת Studio, GetAsync, SetAsync, UpdateAsync, set ו-update
- Roblox Creator Docs: Best practices for data stores (באנגלית). מפתח אחד לכל שחקן, נתונים בזיכרון, ניסיונות חוזרים עם הפסקה שגדלה, מודולים של צד שלישי
- Roblox Creator Docs: Data store error codes and limits (באנגלית). קודי שגיאות, מגבלות בקשות של שרת ומשחק, מגבלות גודל, קצב ואחסון
- Roblox Creator Docs: Versioning, listing and caching (באנגלית). גרסאות שעתיות, snapshots, מטמון של 4 שניות, מה אפשר לשמור
- Roblox Creator Docs: Implement player data and purchasing systems (באנגלית). הדוגמה הרשמית, נעילת סשן, טעינות שנכשלו, שמירה אוטומטית כל 180 שניות
- Roblox Creator Docs: Data Stores Manager (באנגלית). צפייה במפתחות, החזרת גרסאות, מחיקת נתונים
- Roblox Engine API: DataModel:BindToClose (באנגלית). 30 שניות לכיבוי
איך הקוד נבדק: כל סקריפט בעמוד הזה עובר את בודק הטיפוסים המחמיר של Luau עם הגדרות ה-API של Roblox (luau-lsp, 20 בנובמבר 2026). בדיקת טיפוסים תופסת שגיאות בשמות API וטיפוסים שגויים, אבל לא שגיאות בלוגיקת המשחק, אז בדקו הכול ב-Studio לפני הפרסום.