خريطة التجزئة لمخزن الذاكرة

*This content is translated using AI (Beta) and may contain errors. To view this page in English, click here.

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

الحدود

تمتلك خرائط التجزئة حدًا لحجم المفتاح يبلغ 128 حرفًا وحدًا لحجم القيمة يبلغ 32 كيلوبايت.

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

الحصول على خريطة تجزئة

للحصول على خريطة تجزئة، قم باستدعاء MemoryStoreService:GetHashMap() مع اسم لخريطة التجزئة. الاسم عالمي داخل اللعبة، لذا يمكنك الوصول إلى نفس خريطة التجزئة على أي نص باستخدام هذا الاسم.

الحصول على خريطة تجزئة

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")

بعد الحصول على خريطة التجزئة، استخدم أي من الدوال التالية لقراءة أو كتابة البيانات فيها:

الدالةالإجراء
MemoryStoreHashMap:SetAsync()أضف مفتاحًا جديدًا أو استبدل القيمة إذا كان المفتاح موجودًا بالفعل.
MemoryStoreHashMap:GetAsync()اقرأ مفتاحًا معينًا.
MemoryStoreHashMap:ListItemsAsync()قم بإدراج العناصر في خريطة التجزئة.
MemoryStoreHashMap:UpdateAsync()قم بتحديث قيمة مفتاح بعد استردادها من خريطة التجزئة.
MemoryStoreHashMap:RemoveAsync()إزالة مفتاح من خريطة التجزئة.

للحصول على وثائق معمقة حول كل دالة، انظر MemoryStoreHashMap.

إضافة أو استبدال البيانات

لإضافة مفتاح جديد أو استبدال قيمة مفتاح في خريطة التجزئة، قم باستدعاء MemoryStoreHashMap:SetAsync() مع اسم المفتاح، وقيمته، ووقت انتهاء بالثواني. يقوم النظام تلقائيًا بتنظيف الذاكرة بمجرد انتهاء المفتاح. الحد الأقصى لوقت الانتهاء هو 3,888,000 ثانية (45 يومًا).

إضافة بيانات إلى خريطة تجزئة

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
local setSuccess, _ = pcall(function()
return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
print("تمت العملية بنجاح.")
end

الحصول على البيانات

يمكنك الحصول إما على قيمة مرتبطة بمفتاح معين أو الحصول على عدة أزواج من المفاتيح والقيم في خريطة التجزئة.

الحصول على البيانات بمفتاح واحد

للحصول على قيمة مرتبطة بمفتاح واحد من خريطة التجزئة، استدعِ MemoryStoreHashMap:GetAsync() مع اسم المفتاح.

الحصول على مفتاح معين من خريطة التجزئة

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
local setSuccess, _ = pcall(function()
return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
print("تمت العملية بنجاح.")
end
local item
local getSuccess, getError = pcall(function()
item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
print(item)
else
warn(getError)
end

الحصول على البيانات مع عدة أزواج من المفاتيح والقيم

للحصول على جميع أزواج المفاتيح والقيم من خريطة التجزئة كعملية واحدة، استدعِ MemoryStoreHashMap:ListItemsAsync() مع حجم الصفحة المرغوب. تقوم هذه الدالة بإدراج جميع المفاتيح الموجودة بطريقة مجدولة. على سبيل المثال، قطعة الكود التالية تسترجع ما يصل إلى 32 عنصرًا من خريطة التجزئة.

إدراج العناصر في خريطة التجزئة

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- الحصول على قائمة من العناصر، 32 عنصرًا في كل مرة
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- الحصول على الصفحة الحالية
local entries = pages:GetCurrentPage()
-- التكرار خلال جميع أزواج المفتاح والقيمة في الصفحة
for _, entry in ipairs(entries) do
print(entry.key .. " : " .. tostring(entry.value))
end
-- التحقق مما إذا تم الوصول إلى الصفحة الأخيرة
if pages.IsFinished then
break
else
print("----------")
-- التقدم إلى الصفحة التالية
pages:AdvanceToNextPageAsync()
end
end
end

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

لاسترداد قيمة مفتاح من خريطة التجزئة وتحديثها، استدعِ MemoryStoreHashMap:UpdateAsync() مع اسم المفتاح، ودالة نداء لتحديث المفتاح، ووقت انتهاء بالثواني.

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

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

تحديث عدد الموارد لمورد في مخزن مشترك

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("ResourceInventory")
local function contributeResources(itemResource, addedCount)
local success, newResourceCount = pcall(function()
return hashMap:UpdateAsync(itemResource, function(resource)
resource = resource or {count = 0}
resource.count = resource.count + addedCount
-- تأكد من أننا لا نتجاوز الحد الأقصى لعدد الموارد
if resource.count > 500 then
resource.count = 500
end
return resource
end, 1200)
end)
if success then
print(newResourceCount)
end
end

تشبه فترة التأخير لـ UpdateAsync() تلك الخاصة بـ GetAsync() و SetAsync() ما لم يكن هناك تنافس.

عندما يحدث تنافس، يقوم النظام تلقائيًا بإعادة محاولة العملية حتى يحدث أحد هذه الثلاثة: تنجح العملية، ترجع دالة النداء nil، أو يتم الوصول إلى الحد الأقصى لعدد المحاولات. إذا وصل النظام إلى الحد الأقصى لعدد المحاولات، فإنه يرجع صراعا.

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

يمكنك استخدام MemoryStoreHashMap:RemoveAsync() لكل من إزالة مفتاح واحد من خريطة التجزئة وحذف جميع البيانات في خريطة التجزئة لمخزن الذاكرة.

إزالة مفتاح

لإزالة مفتاح من خريطة التجزئة، استدعِ MemoryStoreHashMap:RemoveAsync() مع اسم المفتاح.

إزالة مفتاح من خريطة التجزئة

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
local setSuccess, _ = pcall(function()
return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
print("تمت العملية بنجاح.")
end
local removeSuccess, removeError = pcall(function()
hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
warn(removeError)
end

حذف جميع البيانات

لحذف جميع البيانات في خريطة التجزئة، قم بإدراج جميع عناصر لديك باستخدام MemoryStoreHashMap:ListItemsAsync()، ثم قم بإزالتها باستخدام MemoryStoreHashMap:RemoveAsync().

حذف جميع البيانات في خريطة التجزئة

local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- الحصول على قائمة من العناصر، 32 عنصرًا في كل مرة
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- الحصول على الصفحة الحالية
local entries = pages:GetCurrentPage()
local removeSuccess = true
local removeError = nil
-- التكرار خلال جميع أزواج المفتاح والقيمة في الصفحة
for _, entry in ipairs(entries) do
print(entry.key .. " : " .. tostring(entry.value))
removeSuccess, removeError = pcall(function()
hashMap:RemoveAsync(entry.key)
end)
if not removeSuccess then
warn(removeError)
end
end
-- التحقق مما إذا تم الوصول إلى الصفحة الأخيرة
if pages.IsFinished then
print("تم الانتهاء من حذف جميع البيانات.")
break
else
print("----------")
-- التقدم إلى الصفحة التالية
pages:AdvanceToNextPageAsync()
end
end
end
©2026 شركة Roblox Corporation. تُعد منصّة Roblox، وشعار Roblox وشعار "توسيع حدود المخيلة"، من ضمن علاماتنا التجارية المسجّلة وغير المسجّلة في الولايات المتحدة وبلدان أخرى.