باختصار
استخدم 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 التلقائية لطلبات حق النسيان أن تجد بيانات اللاعب، إذا أعددتها.
| النوع | يُحفظ؟ | ملاحظات |
|---|---|---|
| الأرقام والنصوص والقيم المنطقية والمخازن المؤقتة (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 ثانية وعند الخروج وعند إيقاف الخادم، ويرفض حفظ من لم تُحمَّل بياناته.
- في 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) -- يمكن لواجهة المستخدم قراءة هذا وتحذير اللاعب
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.
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
اللاعب متصل بخادم واحد في كل مرة، لكن الحفظ النهائي للخادم القديم قد يكون ما زال جاريًا حين يدخل خادمًا جديدًا: إعادة محاولة بطيئة، أو انتقال (teleport)، أو إعادة دخول سريعة. إذا حمّل الخادم الجديد البيانات أولًا، فستكون لديه بيانات قديمة، ويفوز الخادم الذي يحفظ أخيرًا. وتشير توثيقات 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 ميغابايت في الدقيقة |
| الكتابة في مفتاح واحد من كل الخوادم | 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 الموجودة عندي.
- يمكنه البحث عن 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 الجميعَ من الصفر؛ لا تفعل ذلك أبدًا في لعبة حية.
المصادر والقراءات
- 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 (بالإنجليزية). النسخ كل ساعة، واللقطات، والذاكرة المؤقتة ذات الـ 4 ثوانٍ، وما يمكن حفظه
- Roblox Creator Docs: Implement player data and purchasing systems (بالإنجليزية). المثال المرجعي، وقفل الجلسة، والتحميل الفاشل، والحفظ التلقائي كل 180 ثانية
- Roblox Creator Docs: Data Stores Manager (بالإنجليزية). عرض المفاتيح، واستعادة النسخ، وحذف البيانات
- Roblox Engine API: DataModel:BindToClose (بالإنجليزية). 30 ثانية للإيقاف
كيف فُحص الكود: كل سكربت في هذه الصفحة يجتاز الفاحص الصارم للأنواع في Luau مع تعريفات واجهة Roblox البرمجية (luau-lsp، ٢٠ نوفمبر ٢٠٢٦). فحص الأنواع يكشف الأخطاء في أسماء الواجهات البرمجية والأنواع الخاطئة، لا منطق اللعبة، فجرّب الكود في Studio قبل النشر.