Bản đồ băm, tương tự như 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ông giống như bản đồ sắp xếp, chúng không duy trì bất kỳ đảm bảo sắp xếp nào. Cấu trúc dữ liệu này rất hữu ích cho các trường hợp cần bộ nhớ đệm dữ liệu đơn giản và truy cập nhanh, chẳng hạn như kho hàng chia sẻ, 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 hoạch 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 hạn ngạch 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 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ỳ script nào sử dụng tên này.
Lấy Bản Đồ Bămlocal MemoryStoreService = game:GetService("MemoryStoreService")local hashMap = MemoryStoreService:GetHashMap("HashMap1")
Sau khi bạn có được một bản đồ băm, hãy gọi bất kỳ hàm nào sau đây để đọc hoặc ghi dữ liệu vào nó:
| 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, 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, 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ớ 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).
Thêm Dữ Liệu Vào Một Bản Đồ Băm
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("Thiết lập thành công.")
end
Lấ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.
Lấy Một Khóa Cụ Thể Từ Một Bản Đồ Băm
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("Thiết lập 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)
end
Lấ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 dưới dạng một thao tác duy nhất, gọi MemoryStoreHashMap:ListItemsAsync() với kích thước trang mong muốn. Hàm này liệt kê tất cả các khóa hiện có theo cách phân trang. Ví dụ, đoạn mã sau đây lấy tối đa 32 mục từ bản đồ băm.
Liệt kê các mục trong Mộ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 trang cuối cùng đã được đạt đến chưa
if pages.IsFinished then
break
else
print("----------")
-- Tiến đến trang tiếp theo
pages:AdvanceToNextPageAsync()
end
end
end
Cậ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ị. Vì 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 đây 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ẻ. UpdateAsync() đảm bảo rằng tất cả các đóng góp của người chơi sẽ đi 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.
Cập Nhật Số Lượng Tài Nguyên Cho Một Tài Nguyên Trong Kho Hàng Chia Sẻ
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 UpdateAsync() tương tự như GetAsync() và SetAsync() trừ khi có xung đột.
Khi xảy ra xung đột, 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 đến số lần thử tối đa. Nếu hệ thống đạt số lần thử tối đa, 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, gọi MemoryStoreHashMap:RemoveAsync() với một tên khóa.
Xóa Một Khóa Khỏi Một Bản Đồ Băm
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("Thiết lập thành công.")
end
local removeSuccess, removeError = pcall(function()
hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
warn(removeError)
end
Xó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 bằng MemoryStoreHashMap:ListItemsAsync(), sau đó xóa chúng bằng MemoryStoreHashMap:RemoveAsync().
Xóa Tất Cả Dữ Liệu Trong Mộ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()
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 trang cuối cùng đã được đạt đến chưa
if pages.IsFinished then
print("Đã hoàn thành việc xóa tất cả dữ liệu.")
break
else
print("----------")
-- Tiến đến trang tiếp theo
pages:AdvanceToNextPageAsync()
end
end
end