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

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

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

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

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

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

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

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

1. افتح نافذة إعدادات التجربة ضمن ملف ⟩ إعدادات.
2. انتقل إلى الأمان.
3. قم بتمكين مفتاح تمكين الوصول إلى واجهات برمجة التطبيقات في الاستوديو.
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