شرح · بيانات اللاعب

كيف تحفظ بيانات اللاعب في Roblox Studio عبر DataStore

لا يتذكر Roblox شيئًا عن اللاعب بين الجلسات ما لم يحفظه سكربت على الخادم. في هذا الدليل ستبني وحدة PlayerData تحمّل بيانات كل لاعب وتحتفظ بها في الذاكرة وتحفظها عبر DataStoreService، ثم تتعرف على الاختبار والحدود والطرق التي تضيع بها البيانات المحفوظة.

آخر تحديث ٢٠ نوفمبر ٢٠٢٦القراءة في 15 دبقلم

باختصار

استخدم 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 التلقائية لطلبات حق النسيان أن تجد بيانات اللاعب، إذا أعددتها.

ما الذي يمكن حفظه في مخزن البيانات
النوعيُحفظ؟ملاحظات
الأرقام والنصوص والقيم المنطقية والمخازن المؤقتة (buffers)نعميجب أن تكون النصوص 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) -- يمكن لواجهة المستخدم قراءة هذا وتحذير اللاعب
	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

-- يحفظ الآن دون انتظار المؤقت، للحظات المهمة مثل الشراء.
-- يتوقف حتى ينتهي (yield) ويُرجع 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) -- اللاعبون الذين دخلوا قبل أول require لهذه الوحدة
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، فلن تكتب هذه القيم فوق تقدمه الحقيقي أبدًا. وتضبط الوحدة أيضًا السمة 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 إذا نجح. يتوقف حتى ينتهي (yield).

الوحدة هي المكان الوحيد الذي تعيش فيه البيانات المحفوظة، أما leaderstats فللعرض فقط: ابنها كما في دليل لوحة الصدارة، واملأها من PlayerData.Get(player) داخل معالج Loaded، وحدّث الاثنين عند تغيّر القيمة. لا تقرأ القيم المحفوظة من leaderstats أبدًا، ولا تسمح لسكربت ثانٍ بحفظ المفتاح نفسه أبدًا.

السكربت الذي يستدعي الوحدة بعد دخول اللاعبين يفوته Loaded بالنسبة لهم. اربط المعالج، ثم مرّ أيضًا في حلقة على Players:GetPlayers() وعالج كل من يُرجع له PlayerData.Get(player) جدولًا بالفعل.

تستبدل سكربت حفظ قديمًا، مثل سكربت دليل لوحة الصدارة؟ قيمه تبقى في مخزنه ومفتاحه الخاصين، لذا ستبدأ هذه الوحدة الجميع بالقيم الافتراضية. قبل الإطلاق إما أن توجّه STORE_NAME والبادئة User_ إلى القديمة (يعتبر migrate البيانات التي لا تحمل SchemaVersion نسخة 1 ويملأ الحقول الناقصة)، وإما أن تنقل القيم القديمة، ثم تحذف السكربت القديم.

العملاء لا يغيّرون هذه البيانات مباشرة أبدًا. زر المتجر يُطلق RemoteEvent؛ فيتحقق الخادم من CanSave، ويقارن السعر بـ Coins اللاعب، ويعدّل الجدول، ويستدعي SaveNow. ودليل واجهة المتجر يبني عملية شراء كهذه على جانب الخادم.

تجد مثالًا جاهزًا لإضافة الحقول في دليل محاكي النقر: يضيف PowerLevel وRebirths إلى DEFAULTS وإلى النوع Data، ثم يعدّلهما في الجدول الذي يُرجعه PlayerData.Get. ويعطي migrate الحقول الجديدة للاعبين أصحاب الحفظ القديم.

الخطوة 3: أخبر اللاعب أن بياناته لم تُحمَّل

اللاعب الذي لم تُحمَّل بياناته يجب أن يعرف أن هذه الجلسة لن تُحفظ، حتى يعيد الدخول بدلًا من أن يلعب بلا فائدة. هذا الـ LocalScript يراقب السمة 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

اللاعب متصل بخادم واحد في كل مرة، لكن الحفظ النهائي للخادم القديم قد يكون ما زال جاريًا حين يدخل خادمًا جديدًا: إعادة محاولة بطيئة، أو انتقال (teleport)، أو إعادة دخول سريعة. إذا حمّل الخادم الجديد البيانات أولًا، فستكون لديه بيانات قديمة، ويفوز الخادم الذي يحفظ أخيرًا. وتشير توثيقات 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 ميغابايت في الدقيقة
الكتابة في مفتاح واحد من كل الخوادم4 ميغابايت في الدقيقة، ويُقرَّب كل طلب صعودًا إلى الكيلوبايت التالي
الطلبات المنتظرة30 لكل قائمة انتظار؛ وما يزيد على ذلك يفشل بالأخطاء 301-306
التخزين للعبة كلها500 ميغابايت مع 1 ميغابايت لكل مستخدم على الإطلاق

قِس حجم بيانات اللاعب عبر #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 بأخذ لقطة عبر 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. احفظ بدلًا منه اسمًا أو معرّفًا أو أرقامًا بسيطة، وأعد بناء الكائن عند التحميل.

ValueTooLarge (الخطأ 105)

مفتاح واحد يحمل أكثر من 4,194,304 حرفًا من JSON. قِسه عبر #HttpService:JSONEncode(data)، واحذف ما يمكن إعادة بنائه، أو قسّم البيانات على عدة مفاتيح ثابتة.

لا أخطاء، لكن البيانات لا تُحفظ

ابحث عن تحذير الوحدة Could not load: بعد التحميل الفاشل ترفض الحفظ عمدًا. وإلا فالأرجح أن القيمة تغيّرت في LocalScript، وهذا لا يصل إلى الخادم أبدًا، أو أن سكربتًا آخر يحفظ المفتاح نفسه.

البيانات تُصفَّر في كل مرة أعيد فيها الدخول

المفتاح يتغير بين الجلسات (مكوّن من player.Name، أو غيّرت STORE_NAME)، أو التحميل يفشل فترى القيم الافتراضية، أو لا أحد يستدعي الوحدة فلا تعمل أصلًا. راجع Output وتأكد من أن Main يستدعي PlayerData.

ابنِه باستخدام RoCode

إذا لم ترغب في بناء هذا يدويًا، يستطيع RoCode فعله مباشرة في المكان المفتوح عندك. إنه وكيل ذكاء اصطناعي مستقل لا يتبع 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 بالذكاء الاصطناعي نظامًا تلو الآخر هذا الترتيب. كيف يتصل 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 مع تعريفات واجهة Roblox البرمجية (luau-lsp، ٢٠ نوفمبر ٢٠٢٦). فحص الأنواع يكشف الأخطاء في أسماء الواجهات البرمجية والأنواع الخاطئة، لا منطق اللعبة، فجرّب الكود في Studio قبل النشر.

جرّب RoCode على لعبتك أنت.

رصيد مجاني كل يوم ودون بطاقة. ثبّت الإضافة، وصف الميزة، وراجع ما يظهر في Studio.