Bản đồ băm, giống như các bản đồ đã sắp xếp, cho phép bạn lưu trữ dữ liệu trong bộ nhớ dưới dạng cặp khóa-giá trị. Khác với các bản đồ đã sắp xếp, chúng không duy trì bất kỳ đảm bảo nào về thứ tự. Cấu trúc dữ liệu này rất hữu ích trong các trường hợp yêu cầu lưu trữ dữ liệu đơn giản và truy cập nhanh, chẳng hạn như kho hàng chia sẻ, các nhà đấu giá vật lý, và nhiều hơn nữa. Bản đồ băm tự động xử lý việc phân chia dữ liệu của bạn và rất hữu ích nếu bạn có hơn 1.000 khóa. Đối với các không gian khóa nhỏ hơn, chúng tôi khuyên bạn nên sử dụng bản đồ đã sắp xếp.
Giới hạn
Bản đồ băm có giới hạn kích thước khóa là 128 ký tự và giới hạn kích thước giá trị là 32 KB.
Ngoài ra, bản đồ băm sử dụng cùng yêu cầu API và giới hạn không gian bộ nhớ như các cấu trúc dữ liệu bộ nhớ khác.
Lấy bản đồ băm
Để lấy một bản đồ băm, gọi MemoryStoreService:GetHashMap() với một tên cho bản đồ băm. Tên này là toàn cầu trong trò chơi, vì vậy bạn có thể truy cập cùng một bản đồ băm trên bất kỳ mã kịch bản nào sử dụng tên này.
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")Sau khi bạn lấy được bản đồ băm, hãy gọi bất kỳ chức năng nào sau đây để đọc hoặc ghi dữ liệu trong đó:
| Chức năng | Hành động |
|---|---|
| MemoryStoreHashMap:SetAsync() | Thêm một khóa mới hoặc ghi đè giá trị nếu khóa đã tồn tại. |
| MemoryStoreHashMap:GetAsync() | Đọc một khóa cụ thể. |
| MemoryStoreHashMap:ListItemsAsync() | Liệt kê các mục trong một bản đồ băm. |
| MemoryStoreHashMap:UpdateAsync() | Cập nhật giá trị của một khóa sau khi lấy nó từ một bản đồ băm. |
| MemoryStoreHashMap:RemoveAsync() | Xóa một khóa khỏi bản đồ băm. |
Để biết tài liệu chi tiết về từng chức năng, hãy xem MemoryStoreHashMap.
Thêm hoặc ghi đè dữ liệu
Để thêm một khóa mới hoặc ghi đè giá trị của một khóa trong bản đồ băm, hãy gọi MemoryStoreHashMap:SetAsync() với tên khóa, giá trị của nó và thời gian hết hạn tính bằng giây. Bộ nhớ sẽ tự động dọn dẹp khi khóa hết hạn. Thời gian hết hạn tối đa là 3.888.000 giây (45 ngày).
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("Thêm thành công.")
endLấy dữ liệu
Bạn có thể lấy giá trị liên quan đến một khóa cụ thể hoặc lấy nhiều cặp khóa-giá trị trong bản đồ băm.
Lấy dữ liệu với một khóa
Để lấy giá trị liên quan đến một khóa từ bản đồ băm, gọi MemoryStoreHashMap:GetAsync() với tên khóa.
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("Thêm thành công.")
end
local item
local getSuccess, getError = pcall(function()
item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
print(item)
else
warn(getError)
endLấy dữ liệu với nhiều cặp khóa-giá trị
Để lấy tất cả các cặp khóa-giá trị từ bản đồ băm như một thao tác duy nhất, hãy gọi MemoryStoreHashMap:ListItemsAsync() với kích thước trang mong muốn. Chức năng này liệt kê tất cả các khóa hiện có theo dạng phân trang. Ví dụ, đoạn mã sau sẽ lấy tối đa 32 mục từ bản đồ băm.
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- Lấy danh sách các mục, 32 mục một lần
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- Lấy trang hiện tại
local entries = pages:GetCurrentPage()
-- Lặp qua tất cả các cặp khóa-giá trị trên trang
for _, entry in ipairs(entries) do
print(entry.key .. " : " .. tostring(entry.value))
end
-- Kiểm tra xem đã đến trang cuối chưa
if pages.IsFinished then
break
else
print("----------")
-- Tiến tới trang tiếp theo
pages:AdvanceToNextPageAsync()
end
end
endCập nhật dữ liệu
Để lấy giá trị của một khóa từ một bản đồ băm và cập nhật nó, gọi MemoryStoreHashMap:UpdateAsync() với tên khóa, một hàm callback để cập nhật khóa, và một thời gian hết hạn tính bằng giây.
Đối với hầu hết các trò chơi, nhiều máy chủ có thể cập nhật cùng một khóa đồng thời và thay đổi giá trị. Bởi vì MemoryStoreHashMap:UpdateAsync() luôn sửa đổi giá trị mới nhất trước khi cập nhật, bạn nên sử dụng nó để đọc giá trị mới nhất làm đầu vào cho hàm callback của bạn.
Ví dụ, đoạn mã sau cập nhật số lượng tài nguyên của một tài nguyên trong kho hàng chia sẻ. MemoryStoreHashMap:UpdateAsync() đảm bảo rằng tất cả các đóng góp của người chơi sẽ được đưa vào kho hàng chia sẻ này, ngay cả khi những đóng góp này được thực hiện đồng thời. Trong hàm này, nó cũng thực thi số lượng tài nguyên tối đa là 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
-- đảm bảo rằng chúng ta không vượt quá số lượng tài nguyên tối đa
if resource.count > 500 then
resource.count = 500
end
return resource
end, 1200)
end)
if success then
print(newResourceCount)
end
endĐộ trễ cho MemoryStoreHashMap:UpdateAsync() tương tự như MemoryStoreHashMap:GetAsync() và MemoryStoreHashMap:SetAsync() trừ khi có tình trạng cạnh tranh.
Khi xảy ra tình trạng cạnh tranh, hệ thống sẽ tự động thử lại thao tác cho đến khi một trong ba điều này xảy ra: thao tác thành công, hàm callback trả về nil, hoặc đạt tối đa số lần thử. Nếu hệ thống đạt tối đa số lần thử, nó sẽ trả về một xung đột.
Xóa dữ liệu
Bạn có thể sử dụng MemoryStoreHashMap:RemoveAsync() để xóa một khóa khỏi bản đồ băm và xóa tất cả dữ liệu trong một bản đồ băm bộ nhớ.
Xóa một khóa
Để xóa một khóa khỏi bản đồ băm, hãy gọi MemoryStoreHashMap:RemoveAsync() với tên khóa.
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("Thêm thành công.")
end
local removeSuccess, removeError = pcall(function()
hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
warn(removeError)
endXóa tất cả dữ liệu
Để xóa tất cả dữ liệu trong một bản đồ băm, liệt kê tất cả các mục của bạn với MemoryStoreHashMap:ListItemsAsync(), sau đó xóa chúng với MemoryStoreHashMap:RemoveAsync().
local MemoryStoreService = game:GetService("MemoryStoreService")
local hashMap = MemoryStoreService:GetHashMap("HashMap1")
-- Lấy danh sách các mục, 32 mục một lần
local success, pages = pcall(function()
return hashMap:ListItemsAsync(32)
end)
if success then
while true do
-- Lấy trang hiện tại
local entries = pages:GetCurrentPage()
local removeSuccess = true
local removeError = nil
-- Lặp qua tất cả các cặp khóa-giá trị trên trang
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
-- Kiểm tra xem đã đến trang cuối chưa
if pages.IsFinished then
print("Đã xóa tất cả dữ liệu.")
break
else
print("----------")
-- Tiến tới trang tiếp theo
pages:AdvanceToNextPageAsync()
end
end
end