تخزين البيانات

تتيح لك DataStoreService تخزين البيانات التي تحتاج إلى الاستمرار بين الجلسات، مثل العناصر في جرد اللاعب أو نقاط المهارة. تعتبر تخزين البيانات متسقة لكل لعبة، لذا يمكن لأي مكان في اللعبة الوصول إلى نفس البيانات وتغييرها، بما في ذلك الأماكن على خوادم مختلفة.

إذا كنت ترغب في إضافة تحكم دقيق في الأذونات لتخزين البيانات الخاصة بك والوصول إليها خارج الاستوديو أو خوادم Roblox، يمكنك استخدام Open Cloud APIs لتخزين البيانات.

لعرض ومراقبة جميع تخزين البيانات في لعبة من خلال مركز المبدعين، استخدم مدير تخزين البيانات.

لبيانات مؤقتة تحتاج إلى تحديثها أو الوصول إليها بشكل متكرر، استخدم تخزين الذاكرة.

تمكين الوصول إلى الاستوديو

بشكل افتراضي، لا يمكن للألعاب التي تم اختبارها في الاستوديو الوصول إلى تخزين البيانات، لذا يجب عليك أولاً تمكينها. يمكن أن يكون الوصول إلى تخزين البيانات في الاستوديو خطيرًا للألعاب الحية لأن الاستوديو يصل إلى نفس تخزين البيانات مثل تطبيق العميل. لتجنب الكتابة فوق بيانات الإنتاج، لا تقم بتمكين هذا الإعداد للألعاب الحية. بدلاً من ذلك، قم بتمكينه لإصدار اختبار منفصل من اللعبة.

لتمكين الوصول إلى الاستوديو في لعبة منشورة:

1. افتح نافذة ملف ⟩ إعدادات التجربة في الاستوديو.
2. انتقل إلى الأمان.
3. قم بتمكين مفتاح تمكين الوصول إلى الاستوديو لخدمات API.
4. انقر على حفظ.

الوصول إلى تخزين البيانات

للوصول إلى تخزين البيانات داخل لعبة:

1. أضف DataStoreService إلى Script على جانب الخادم.
2. استخدم دالة GetDataStore() وحدد اسم تخزين البيانات الذي تريد استخدامه. إذا لم يكن تخزين البيانات موجودًا، يقوم الاستوديو بإنشاء واحد عند حفظ بيانات لعبتك لأول مرة.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

إنشاء البيانات

تخزين البيانات هو في الأساس قاموس، مشابه لجدول Luau. يتم فهرسة كل قيمة في تخزين البيانات بواسطة مفتاح فريد، مثل Player.UserId الفريد للمستخدم أو سلسلة مسماة لعرض ترويجي للعبة.

لإنشاء إدخال جديد، استدعِ SetAsync() مع اسم المفتاح وقيمة.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, errorMessage = pcall(function()
	gameStore:SetAsync("User_1234", 50)
end)
if not success then
	print(errorMessage)
end

تحديث البيانات

لتغيير أي قيمة مخزنة في تخزين البيانات، استدعِ UpdateAsync() مع اسم مفتاح الإدخال ودالة رد نداء تحدد كيف تريد تحديث الإدخال. تأخذ هذه الدالة القيمة الحالية وتعيد قيمة جديدة بناءً على المنطق الذي تحدده. إذا أعادت الدالة nil، يتم إلغاء عملية الكتابة ولا يتم تحديث القيمة.

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local function makeNameUpper(currentName)
	local nameUpper = string.upper(currentName)
	return nameUpper
end

local success, updatedName = pcall(function()
	return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
end)
if success then
	print("Uppercase Name:", updatedName)
end

تعيين مقابل تحديث

استخدم التعيين لتحديث مفتاح محدد بسرعة. دالة SetAsync():

• يمكن أن تسبب عدم اتساق البيانات إذا حاول خادمان تعيين نفس المفتاح في نفس الوقت
• تحسب فقط ضد حد الكتابة

استخدم التحديث للتعامل مع محاولات متعددة للخادم. دالة UpdateAsync():

• تقرأ القيمة الحالية للمفتاح من الخادم الذي قام بتحديثه آخر مرة قبل إجراء أي تغييرات
• أبطأ لأنها تقرأ قبل الكتابة
• تحسب ضد كل من حدود القراءة والكتابة

قراءة البيانات

لقراءة قيمة إدخال تخزين البيانات، استدعِ GetAsync() مع اسم مفتاح الإدخال.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, currentGame = pcall(function()
	return gameStore:GetAsync("User_1234")
end)
if success then
	print(currentGame)
end

زيادة البيانات

لزيادة عدد صحيح في تخزين البيانات، استدعِ IncrementAsync() مع اسم مفتاح الإدخال ورقم لمقدار تغيير القيمة. IncrementAsync() هي دالة ملائمة تتيح لك تجنب استدعاء UpdateAsync() وزيادة العدد يدويًا.

local DataStoreService = game:GetService("DataStoreService")

local gameStore = DataStoreService:GetDataStore("PlayerGame")

local success, newGame = pcall(function()
	return gameStore:IncrementAsync("Player_1234", 1)
end)
if success then
	print(newGame)
end

إزالة البيانات

لإزالة إدخال وإرجاع القيمة المرتبطة بالمفتاح، استدعِ RemoveAsync().

local DataStoreService = game:GetService("DataStoreService")

local nicknameStore = DataStoreService:GetDataStore("Nicknames")

local success, removedValue = pcall(function()
	return nicknameStore:RemoveAsync("User_1234")
end)
if success then
	print(removedValue)
end

البيانات الوصفية

هناك نوعان من البيانات الوصفية المرتبطة بالمفاتيح:

• محددة بواسطة الخدمة: بيانات وصفية افتراضية للقراءة فقط، مثل وقت التحديث الأخير ووقت الإنشاء. كل كائن لديه بيانات وصفية محددة بواسطة الخدمة.
• محددة بواسطة المستخدم: بيانات وصفية مخصصة للتوسيم والتصنيف. يتم تعريفها باستخدام كائن DataStoreSetOptions ودالة SetMetadata().

لإدارة البيانات الوصفية، قم بتوسيع دوال SetAsync(), UpdateAsync(), GetAsync(), IncrementAsync(), و RemoveAsync().

• SetAsync() يقبل الوسيطين الثالث والرابع الاختياريين:

  • جدول من UserIds. يمكن أن يساعد ذلك في تتبع وإزالة حقوق الطبع والنشر للمحتوى والملكية الفكرية.

  • كائن DataStoreSetOptions، حيث يمكنك تعريف بيانات وصفية مخصصة باستخدام دالة SetMetadata().

    local DataStoreService = game:GetService("DataStoreService")
    
    local gameStore = DataStoreService:GetDataStore("PlayerGame")
    
    local setOptions = Instance.new("DataStoreSetOptions")
    setOptions:SetMetadata({["GameElement"] = "Fire"})
    
    local success, errorMessage = pcall(function()
        gameStore:SetAsync("User_1234", 50, {1234}, setOptions)
    end)
    if not success then
        print(errorMessage)
    end

• GetAsync(), IncrementAsync(), و RemoveAsync() تعيد قيمة ثانية في كائن DataStoreKeyInfo. تحتوي هذه القيمة الثانية على كل من الخصائص المحددة بواسطة الخدمة والدوال لجلب البيانات الوصفية المحددة بواسطة المستخدم.

  • دالة GetUserIds() تجلب جدول UserIds الذي مررته إلى SetAsync().
  • دالة GetMetadata() تجلب البيانات الوصفية المحددة بواسطة المستخدم التي مررتها إلى SetAsync() من خلال SetMetadata().
  • خاصية Version تجلب إصدار المفتاح.
  • خاصية CreatedTime تجلب الوقت الذي تم فيه إنشاء المفتاح، مُنسقًا كعدد المللي ثانية منذ بداية العصر.
  • خاصية UpdatedTime تجلب آخر وقت تم فيه تحديث المفتاح، مُنسقًا كعدد المللي ثانية منذ بداية العصر.

  local DataStoreService = game:GetService("DataStoreService")
  
  local gameStore = DataStoreService:GetDataStore("PlayerGame")
  
  local success, currentGame, keyInfo = pcall(function()
      return gameStore:GetAsync("User_1234")
  end)
  if success then
      print(currentGame)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

• تأخذ دالة رد النداء لـ UpdateAsync() معلمة إضافية في كائن DataStoreKeyInfo الذي يصف حالة المفتاح الحالية. تعيد القيمة المعدلة، والمفاتيح المرتبطة بـ UserIds، وبيانات المفتاح الوصفية.

  local DataStoreService = game:GetService("DataStoreService")
  
  local nicknameStore = DataStoreService:GetDataStore("Nicknames")
  
  local function makeNameUpper(currentName, keyInfo)
      local nameUpper = string.upper(currentName)
      local userIDs = keyInfo:GetUserIds()
      local metadata = keyInfo:GetMetadata()
      return nameUpper, userIDs, metadata
  end
  
  local success, updatedName, keyInfo = pcall(function()
      return nicknameStore:UpdateAsync("User_1234", makeNameUpper)
  end)
  if success then
      print(updatedName)
      print(keyInfo.Version)
      print(keyInfo.CreatedTime)
      print(keyInfo.UpdatedTime)
      print(keyInfo:GetUserIds())
      print(keyInfo:GetMetadata())
  end

لحدود تعريف البيانات الوصفية، انظر حدود البيانات الوصفية.

تخزين البيانات المرتبة

بشكل افتراضي، لا تقوم تخزين البيانات بفرز محتواها. إذا كنت بحاجة إلى الحصول على البيانات بطريقة مرتبة، مثل إحصائيات لوحة المتصدرين المستمرة، استدعِ GetOrderedDataStore() بدلاً من GetDataStore().

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

تدعم تخزين البيانات المرتبة نفس الوظائف الأساسية مثل تخزين البيانات الافتراضي، بالإضافة إلى دالة فريدة GetSortedAsync(). تسترجع هذه الدالة مفاتيح مرتبة متعددة بناءً على ترتيب فرز محدد، وحجم الصفحة، والقيم الدنيا/القصوى.

المثال التالي يقوم بفرز بيانات الشخصيات إلى صفحات تحتوي على ثلاثة إدخالات، كل منها بترتيب تنازلي، ثم يتكرر عبر الصفحات ويخرج اسم كل شخصية وعمرها.

local DataStoreService = game:GetService("DataStoreService")

local characterAgeStore = DataStoreService:GetOrderedDataStore("CharacterAges")

-- يملأ تخزين البيانات المرتبة
local characters = {
	Mars = 19,
	Janus = 20,
	Diana = 18,
	Venus = 25,
	Neptune = 62
}
for char, age in characters do
	local success, errorMessage = pcall(function()
		characterAgeStore:SetAsync(char, age)
	end)
	if not success then
		print(errorMessage)
	end
end

-- يفرز البيانات بترتيب تنازلي إلى صفحات تحتوي على ثلاثة إدخالات لكل منها
local success, pages = pcall(function()
	return characterAgeStore:GetSortedAsync(false, 3)
end)
if success then
	while true do
		-- يحصل على الصفحة الحالية (الأولى)
		local entries = pages:GetCurrentPage()
		-- يتكرر عبر جميع أزواج المفتاح والقيمة في الصفحة
		for _, entry in entries do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- يتحقق مما إذا كانت الصفحة الأخيرة قد تم الوصول إليها
		if pages.IsFinished then
			break
		else
			print("----------")
			-- يتقدم إلى الصفحة التالية
			pages:AdvanceToNextPageAsync()
		end
	end
end

قراءة إدخالات متعددة

لقراءة إدخالات تخزين البيانات المرتبة متعددة في طلب واحد، استدعِ BatchGetAsync() مع مصفوفة من المفاتيح. هذه هي النسخة المجمعة لقراءة الإدخالات واحدة تلو الأخرى باستخدام GetAsync().

تُعيد BatchGetAsync() قاموسًا يربط كل مفتاح مطلوب بجدول يحتوي على حقل value. المفاتيح التي لا توجد تُستبعد من القاموس، لذا تأكد من أن المفتاح موجود قبل قراءة قيمته.

كل مفتاح تطلبه يُحسب كطلب قراءة واحد، لذا فإن استدعاء واحد لـ N مفاتيح يُحسب كـ N طلبات ضد حد القراءة لتخزين البيانات المرتبة.

المثال التالي يقرأ ثلاث درجات للاعبين في طلب واحد، ثم يتكرر عبر المفاتيح ويخرج كل درجة موجودة.

local DataStoreService = game:GetService("DataStoreService")

local playerScores = DataStoreService:GetOrderedDataStore("PlayerScores")
local keys = {"Player_123", "Player_456", "Player_789"}

local success, results = pcall(function()
	return playerScores:BatchGetAsync(keys)
end)
if success then
	for _, key in keys do
		local entry = results[key]
		if entry then
			print(key .. " : " .. tostring(entry.value))
		else
			print(key .. " ليس له إدخال محفوظ")
		end
	end
end