工坊手册

主题

MemoryStoreSortedMap ​

概览 ​

字段值
KindData · 数据 Data
Realmserver

MemoryStoreSortedMap 表示 MemoryStore 中的有序集合，条目按排序键优先、键其次的规则排列：数字排序键在最前，字符串排序键随后，没有排序键的条目排在最后。它支持用 SetAsync、GetAsync、RemoveAsync 增删改查单条数据，用 UpdateAsync 对指定键执行原子变换，借助 GetRangeAsync 按升序或降序成批读取条目，并可通过 GetSizeAsync 与 DeleteAsync 统计规模或整体清空。

适用场景 ​

适合在服务端维护一批带顺序语义的共享数据，先写入带排序键的条目，再按升序或降序成批取出其中一段做后续处理。

使用要点 ​

先通过 game:GetService("MemoryStoreService") 取得服务实例，再调用其 GetSortedMap("名称") 获得 MemoryStoreSortedMap，传入的是业务键名。写入时调用 SetAsync 传入 key、value 与可选 sortKey 及 MemoryStoreSortedMapSetOptions；读取单条用 GetAsync，原子更新用 UpdateAsync 并让变换函数返回新值与可选排序键。批量读取用 GetRangeAsync，方向参数使用 Enums.SortDirection.Ascending 或 Enums.SortDirection.Descending，并配合 MemoryStoreSortedMapGetRangeOptions 控制范围；最后可用 GetSizeAsync 统计条数、DeleteAsync 清空集合。

注意事项 ​

MemoryStoreSortedMap 不可直接构造，必须通过 MemoryStoreService:GetSortedMap(name) 获取。key 是业务字符串键名，不是 Enums.* 枚举值；GetRangeAsync 的 direction 使用 Enums.SortDirection.Ascending/Descending；UpdateAsync 的 transformFunction 应返回 newValue 和可选 newSortKey。

代码示例 ​

获取 SortedMap 并写入排行榜分数 ​

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    local key = 'player:1001'
    local score = 1200
    local options = MemoryStoreSortedMapSetOptions.New()
    sortedMap:SetAsync(key, score, score, options)

    local pages = sortedMap:GetRangeAsync(Enums.SortDirection.Descending, 10)
    for _, item in ipairs(pages:GetCurrentPage()) do
        print(item.Key, item.Value)
    end
end)

函数 (7) ​

SetAsync ​

签名：SetAsync(key: String, value: Any, sortKey?: Any, options?: MemoryStoreSortedMapSetOptions) -> Any, Any (依次返回成功写入的 value 与 sortKey；条件不满足时返回 nil。)

向有序映射中设置指定 key 的值，并可附带排序键和条件选项。

参数类型说明
keyString键名
valueAny数据值
sortKey?Any排序键, 可为数字/字符串/nil
options?MemoryStoreSortedMapSetOptions可选参数 (条件修饰/TTL 等), 可通过 MemoryStoreSortedMapSetOptions.New(...) 或 MemoryStoreSortedMapSetOptions(...) 创建

返回值 Any, Any (依次返回成功写入的 value 与 sortKey；条件不满足时返回 nil。)

示例代码

写入 SortedMap 值和排序键

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    local options = MemoryStoreSortedMapSetOptions.New()
    local score = 1200
    local writtenValue, writtenSortKey = sortedMap:SetAsync('player:1001', score, score, options)
    print('写入结果:', writtenValue, writtenSortKey)
end)

GetAsync ​

签名：GetAsync(key: String) -> Any, Any (依次返回 value 与 sortKey；键不存在时两者均为 nil。)

从有序映射中获取指定 key 对应的值。

参数类型说明
keyString键名

返回值 Any, Any (依次返回 value 与 sortKey；键不存在时两者均为 nil。)

示例代码

读取 SortedMap 键值

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    local score, sortKey = sortedMap:GetAsync('player:1001')
    print('玩家分数和排序键:', score, sortKey)
end)

RemoveAsync ​

签名：RemoveAsync(key: String) -> void

从有序映射中删除指定 key 的条目。

参数类型说明
keyString键名

返回值 void

示例代码

删除 SortedMap 键

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    sortedMap:RemoveAsync('player:1001')
end)

GetRangeAsync ​

签名：GetRangeAsync(direction: SortDirection, count: Int, options?: MemoryStoreSortedMapGetRangeOptions) -> MemoryStoreSortedMapPages (分页迭代器)

范围分页查询。用于从有序映射（MemoryStoreSortedMap）中按方向批量读取若干条目，返回一个分页迭代器（MemoryStoreSortedMapPages），通过迭代器逐页获取键值数据。

参数类型说明
directionSortDirection排序方向，使用 Enums.SortDirection.Ascending 或 Enums.SortDirection.Descending。
countInt每页数量
options?MemoryStoreSortedMapGetRangeOptions可选参数, 可通过 MemoryStoreSortedMapGetRangeOptions.New(...) 或 MemoryStoreSortedMapGetRangeOptions(...) 创建

返回值 MemoryStoreSortedMapPages (分页迭代器)

示例代码

按分数降序读取排行榜

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    local pages = sortedMap:GetRangeAsync(Enums.SortDirection.Descending, 10)
    for _, item in ipairs(pages:GetCurrentPage()) do
        print(item.Key, item.Value)
    end
end)

GetSizeAsync ​

签名：GetSizeAsync() -> Int (元素数量)

获取有序映射中当前存储的元素总数。

返回值 Int (元素数量)

示例代码

读取 SortedMap 元素数量

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    local size = sortedMap:GetSizeAsync()
    print('排行榜人数:', size)
end)

DeleteAsync ​

签名：DeleteAsync() -> void

删除整个 MemoryStoreSortedMap 集合，包括其中的所有键值对。

返回值 void

示例代码

仅删除确认可清理的文档沙盒 SortedMap

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    -- DeleteAsync 会删除整张表，只能用于确认可清理的文档沙盒
    local sortedMap = MemoryStoreService:GetSortedMap('DocumentationSandboxSortedMap')

    sortedMap:DeleteAsync()
end)

UpdateAsync ​

签名：UpdateAsync(key: String, transformFunction: Function, sortKey?: Any) -> Any, Any (依次返回更新后的 value 与 sortKey；transform 返回 nil 时两者均为 nil。)

通过比较并交换语义原子更新指定 key 的值和排序键；发生并发冲突时可能重新调用 transformFunction。

参数类型说明
keyString键名
transformFunctionFunction变换函数 (oldValue, oldSortKey) → newValue, newSortKey?, options?
sortKey?Any初始 sortKey 兜底 (仅在键首次创建时生效)

返回值 Any, Any (依次返回更新后的 value 与 sortKey；transform 返回 nil 时两者均为 nil。)

示例代码

原子更新分数和排序键

lua
-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    local MemoryStoreService = game:GetService('MemoryStoreService')
    local sortedMap = MemoryStoreService:GetSortedMap('season_score')

    local newScore, newSortKey = sortedMap:UpdateAsync('player:1001', function(oldValue, oldSortKey)
        local score = (oldValue or 0) + 10
        return score, score
    end, 0)
    print('更新后分数和排序键:', newScore, newSortKey)
end)