מדריך · נתוני שחקן

איך שומרים נתוני שחקן ב-Roblox Studio עם DataStore

Roblox לא זוכרת כלום על שחקן בין סשנים, אם סקריפט שרת לא שמר את זה. במדריך הזה תבנו מודול PlayerData שטוען, מחזיק בזיכרון ושומר את הנתונים של כל שחקן דרך DataStoreService, ואז תעברו על הבדיקה, המגבלות והדרכים שבהן נתונים שמורים הולכים לאיבוד.

עודכן 20 בנובמבר 202615 דק׳ קריאהמאת:

בקצרה

השתמשו ב-DataStoreService מתוך Script של שרת: טענו את נתוני השחקן דרך GetAsync כשהוא נכנס, החזיקו אותם בטבלה בזמן שהוא משחק, ושמרו דרך UpdateAsync לפי טיימר, ביציאה (PlayerRemoving) ובכיבוי השרת (game:BindToClose). עטפו כל קריאה ב-pcall ונסו שוב כמה פעמים קריאות שנכשלו.

  • כדי לבדוק ב-Studio, פרסמו את הפלייס והפעילו את File > Experience Settings > Security > Enable Studio Access to API Services במשחק בדיקה נפרד: Studio משתמש באותם נתונים כמו השרתים החיים.
  • אם נתוני השחקן לא נטענו, אף פעם אל תשמרו את השחקן הזה. שמירה של ערכי ברירת המחדל תדרוס את ההתקדמות האמיתית שלו.
  • שמרו טבלה אחת לכל שחקן תחת מפתח אחד, למשל User_12345, ושמרו לפי טיימר, לא בכל שינוי.
  • להחלפת פריטים או לפריטים בתשלום הוסיפו נעילת סשן, כדי ששני שרתים לא יוכלו לשמור את אותו שחקן.
בעמוד הזה
  1. גישת Studio
  2. איך DataStore עובד
  3. GetAsync ו-UpdateAsync
  4. 1. המודול PlayerData
  5. איך המודול בנוי
  6. 2. עבודה עם הנתונים
  7. 3. אזהרה
  8. 4. בדיקה ב-Studio
  9. למה נתונים הולכים לאיבוד
  10. נעילת סשן
  11. מגבלות
  12. גרסאות וגיבויים
  13. Common errors
  14. With RoCode
  15. שאלות נפוצות
  16. מקורות וקריאה נוספת

לפני שמתחילים: הפעילו גישת Studio בעותק בדיקה

משחק שרץ ב-Studio לא יכול לפנות למאגרי נתונים עד שתתירו את זה. להיתר יש מלכודת שהתיעוד של Roblox מזהיר עליה: Studio אז קורא וכותב לאותם מאגרי נתונים כמו המשחק החי, ולכן בדיקה שמאפסת את המטבעות שלכם ב-Studio מאפסת אותם גם במשחק החי, ובאג בקוד הבדיקה יכול לקלקל מפתחות של שחקנים אמיתיים.

  1. צרו עותק בדיקה. שמרו את הפלייס לקובץ, פתחו את העותק, בחרו File > Publish to Roblox As ולחצו על Create new game. אל תוסיפו אותו כפלייס בתוך המשחק החי: כל הפלייסים של משחק אחד חולקים את אותם מאגרי נתונים.
  2. בעותק הבדיקה פתחו File > Experience Settings ועברו ל-Security.
  3. הפעילו את Enable Studio Access to API Services ולחצו על Save.

קריאות למאגרי נתונים עובדות רק ב-Script של שרת; LocalScript שינסה יקבל שגיאה, ולכן לקוחות לא יכולים לכתוב נתונים שמורים. כשכפתור צריך לשנות אותם, הלקוח מבקש מהשרת דרך RemoteEvent, והשרת מחליט (ראו את המדריך ל-RemoteEvents, באנגלית).

איך מאגרי נתונים שומרים נתוני שחקנים

איורהבדיקה משלב 4 של המדריך בגרסה מואצת: Play, Stop שומר את הסשן במאגר הנתונים, Play נוסף טוען אותו, ולכן ה-Output מציג 200.

מאגר נתונים (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 שניות, ביציאה ובכיבוי השרת, ומסרב לשמור את מי שהנתונים שלו לא נטענו.

  1. ב-Explorer רחפו מעל ServerScriptService, לחצו על + והכניסו ModuleScript. שנו את השם שלו ל-PlayerData והחליפו את התוכן בקוד שלמטה.
  2. ModuleScript רץ רק כשסקריפט כלשהו טוען אותו (require). הכניסו ל-ServerScriptService Script בשם Main עם השורה הזו: local PlayerData = require(game:GetService("ServerScriptService").PlayerData). סקריפטי שרת אחרים טוענים אותו באותה דרך.
  3. שנו את DEFAULTS ואת הטיפוס Data למשחק שלכם, ושמרו שכל שדה יהיה מספר, מחרוזת, בוליאני או טבלה.
ה-Explorer אחרי שלבים 1-3
ServerScriptService
    PlayerData ModuleScript new
    Main Script new
StarterPlayer
    StarterPlayerScripts
        DataWarning LocalScript new
ModuleScript בתוך ServerScriptService בשם PlayerData
-- 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.

LocalScript בתוך StarterPlayerScripts בשם 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

-- השרת קובע את DataLoaded פעם אחת, אחרי הניסיון לטעון את הנתונים של השחקן הזה
player:GetAttributeChangedSignal("DataLoaded"):Connect(showWarning)
showWarning()

שלב 4: בדקו את השמירה ב-Studio

עשו את זה בעותק הבדיקה עם גישת Studio מופעלת.

  1. תנו לעצמכם משהו לשמור. מתחת לשורת ה-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)
  2. לחצו על Play. חלון ה-Output (בתפריט Window או בלשונית Script) יציג את השם שלכם ו-100 (בהרצה הראשונה), בלי האזהרה Could not load.
  3. לחצו על Stop. סיום הבדיקה סוגר את השרת, והמודול שומר אתכם לפני הסגירה.
  4. לחצו שוב על Play. ה-Output אמור להציג 200, 100 יותר מהפעם הקודמת. אם הוא מציג שוב את אותו מספר, השמירה לא עברה: קראו את האזהרות שמעליו.
  5. בדקו את המסלול עם השגיאה. כבו את גישת Studio ולחצו על Play. אחרי כמה שניות של ניסיונות חוזרים ה-Output יציג Could not load User_... ו-100, והבאנר משלב 3 יופיע. עצרו את הבדיקה, הפעילו שוב את הגישה ולחצו על Play: ה-Output יציג 300, ה-200 השמורים שלכם ועוד 100, כי הסשן שנכשל אף פעם לא דרס את הנתונים שלכם.
  6. מחקו את שורת הבדיקה מ-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, קריאה ב-UpdateAsync60 + 40 × שחקנים60 + 40 × שחקנים
כתיבה: SetAsync, IncrementAsync, כתיבה ב-UpdateAsync60 + 40 × שחקנים30 + 5 × שחקנים
רשימה: ListKeysAsync או GetSortedAsync למאגרים ממוינים5 + 2 × שחקנים5 + 2 × שחקנים
מחיקה: RemoveAsync60 + 40 × שחקנים30 + 5 × שחקנים

עם 20 שחקנים שרת יכול לבצע 860 כתיבות רגילות בדקה; השמירה האוטומטית של המודול הזה צורכת בערך 7 מהן, ועוד אחת לכל שחקן שיצא. את התקציב מכלה שמירה בכל מטבע שנאסף. תקציב שני חל על כל המשחק ומתחלק עם Open Cloud: 300 קריאות בדקה ועוד 40 לכל שחקן מחובר, ו-300 כתיבות ועוד 20 לכל שחקן.

מגבלות גודל וקצב
מגבלהערך
שם המאגר, שם המפתח, scope50 תווים כל אחד
ערך במפתח אחד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 שכבר יש לי.

RoCode עושה
  • יכול לחפש 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 מתחיל את כולם מאפס; אף פעם אל תעשו את זה במשחק החי.

מקורות וקריאה נוספת

איך הקוד נבדק: כל סקריפט בעמוד הזה עובר את בודק הטיפוסים המחמיר של Luau עם הגדרות ה-API של Roblox (luau-lsp, 20 בנובמבר 2026). בדיקת טיפוסים תופסת שגיאות בשמות API וטיפוסים שגויים, אבל לא שגיאות בלוגיקת המשחק, אז בדקו הכול ב-Studio לפני הפרסום.

נסו את RoCode במשחק שלכם.

קרדיטים חינמיים בכל יום, בלי כרטיס אשראי. התקינו את הפלאגין, תארו פיצ'ר ובדקו מה מופיע ב-Studio.