DataStoreService

DataStoreService 数据存储服务，提供数据持久化的读写、版本管理和排序查询能力。

Overview

DataStoreService 是游戏持久化存取能力的总入口。通过它可取得普通数据存储、全局数据存储与有序数据存储三类句柄，分别适合玩家进度、跨服配置和排行榜等数据场景；同时支持按名称前缀分页枚举已创建的数据集合，便于梳理存储布局。

Get by:

-- @runtime client
local service = editor:GetService("DataStoreService")

Public

GetDataStore

用于获取一个普通的数据存储集合。普通数据存储以键值方式组织数据，调用方可在同一个集合内通过不同键分别保存和读取数据。

参数

参数	类型	说明
name	String	数据存储名称
scope	String	作用域（可选）
options	DataStoreOptions	存储选项（可选）

返回值

类型	说明
DataStore	数据存储集合对象，用于键值读写

调用 GetDataStore

-- @runtime client
local dataStoreService = editor:GetService("DataStoreService")
local name = "default"  -- String
local scope = "default"  -- String
local options = DataStoreOptions.New()
local result = dataStoreService:GetDataStore(name, scope, options)  -- 返回 DataStore
if result ~= nil then
    print("调用成功，结果: " .. tostring(result))
end

GetGlobalDataStore

用于获取一个全局数据存储集合，其作用等同于使用固定的集合标识和全局作用域获取普通数据存储集合。

参数

参数	类型	说明
options	DataStoreOptions	存储选项（可选）

返回值

类型	说明
DataStore	全局数据存储集合对象

调用 GetGlobalDataStore

-- @runtime client
local dataStoreService = editor:GetService("DataStoreService")
local options = DataStoreOptions.New()
local result = dataStoreService:GetGlobalDataStore(options)  -- 返回 DataStore
if result ~= nil then
    print("调用成功，结果: " .. tostring(result))
end

GetOrderedDataStore

用于获取一个有序数据存储集合。该类集合面向按数值组织与排序的键值数据，适合保存需要体现先后或高低顺序的记录。

参数

参数	类型	说明
name	String	有序数据存储名称
scope	String	作用域（可选）
options	DataStoreOptions	存储选项（可选）

返回值

类型	说明
OrderedDataStore	有序数据存储集合对象，支持按值排序

调用 GetOrderedDataStore

-- @runtime client
local dataStoreService = editor:GetService("DataStoreService")
local name = "default"  -- String
local scope = "default"  -- String
local options = DataStoreOptions.New()
local result = dataStoreService:GetOrderedDataStore(name, scope, options)  -- 返回 OrderedDataStore
if result ~= nil then
    print("调用成功，结果: " .. tostring(result))
end

ListDataStoresAsync

分页列出当前环境中所有普通数据存储集合的信息。通过参数可以控制列出的范围、每页包含的条目数量以及从哪里开始继续列出。

参数

参数	类型	说明
prefix	String	名称前缀过滤（可选）
pageSize	Int	每页数量（可选）
cursor	String	分页游标（可选）
options	DataStoreListOptions	分页选项（可选）

返回值

类型	说明
DataStoreInfoPages	数据存储信息的分页迭代器

协程中分页列出普通 DataStore 集合

-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor:GetService('Task')
local listOptions = DataStoreListOptions.New()
-- ListDataStoresAsync 是异步方法，必须在协程中调用
Task:Spawn(function()
    local pages = DataStoreService:ListDataStoresAsync('', 10, '', listOptions)
    local currentPage = pages:GetCurrentPage()
    print('当前页 DataStore 数量:', #currentPage)
end)

ListOrderedDataStoresAsync

分页列出当前环境中所有有序数据存储集合的信息。调用方可以通过返回的分页信息逐页查看各有序集合的基本情况。

参数

参数	类型	说明
prefix	String	名称前缀过滤（可选）
pageSize	Int	每页数量（可选）
cursor	String	分页游标（可选）
options	DataStoreListOptions	分页选项（可选）

返回值

类型	说明
DataStoreInfoPages	有序数据存储信息的分页迭代器

协程中分页列出有序 OrderedDataStore 集合

-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor:GetService('Task')
local listOptions = DataStoreListOptions.New()
Task:Spawn(function()
    local pages = DataStoreService:ListOrderedDataStoresAsync('', 10, '', listOptions)
    local currentPage = pages:GetCurrentPage()
    print('当前页 OrderedDataStore 数量:', #currentPage)
end)

TotalSummaryAsync

获取当前命名空间的聚合统计信息。该调用不需要额外参数，直接返回统计结果。

返回值

类型	说明
Map	当前 namespace 的聚合统计数据

调用 TotalSummaryAsync

-- @runtime client
local Task = editor:GetService("Task")
Task:Spawn(function()
    local dataStoreService = editor:GetService("DataStoreService")
    local result = dataStoreService:TotalSummaryAsync()  -- 返回 Map
    if result ~= nil then
        for key, item in pairs(result) do
            print(key, item)
        end
    end
end)

RemoveDataStoreAsync

对指定的普通数据存储集合执行删除操作。调用后返回被删除集合的信息对象。

注意： 该操作会删除整个 DataStore 集合。示例仅使用 DocumentationSandbox 专用集合，并与 RestoreDataStoreAsync 示例配对。异步调用必须位于协程中。

参数

参数	类型	说明
name	String	要删除的数据存储名称

返回值

类型	说明
DataStoreInfo	被删除集合的信息对象

删除文档验证专用 DataStore

-- @runtime client
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
Task:Spawn(function()
    local info = service:RemoveDataStoreAsync("DocumentationSandbox")
    print("删除结果:", info)
end)

RemoveOrderedDataStoreAsync

对指定的有序数据存储集合执行删除操作。调用后返回被删除的有序集合信息对象。

注意： 该操作会删除整个 OrderedDataStore 集合。示例仅使用 DocumentationSandboxOrdered 专用集合，并与 RestoreOrderedDataStoreAsync 示例配对。异步调用必须位于协程中。

参数

参数	类型	说明
name	String	要删除的有序数据存储名称

返回值

类型	说明
DataStoreInfo	被删除集合的信息对象

删除文档验证专用 OrderedDataStore

-- @runtime client
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
Task:Spawn(function()
    local info = service:RemoveOrderedDataStoreAsync("DocumentationSandboxOrdered")
    print("删除结果:", info)
end)

RestoreDataStoreAsync

恢复一个此前被删除的普通数据存储集合，并返回恢复后的集合信息。

注意： 该示例与 RemoveDataStoreAsync 的 DocumentationSandbox 专用集合配对；没有可恢复记录时返回空结果。异步调用必须位于协程中。

参数

参数	类型	说明
name	String	要恢复的数据存储名称

返回值

类型	说明
DataStoreInfo	被恢复集合的信息对象

恢复文档验证专用 DataStore

-- @runtime client
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
Task:Spawn(function()
    local info = service:RestoreDataStoreAsync("DocumentationSandbox")
    print("恢复结果:", info)
end)

RestoreOrderedDataStoreAsync

恢复一个此前被删除的有序数据存储集合，并返回恢复后的集合信息。

注意： 该示例与 RemoveOrderedDataStoreAsync 的 DocumentationSandboxOrdered 专用集合配对；没有可恢复记录时返回空结果。异步调用必须位于协程中。

参数

参数	类型	说明
name	String	要恢复的有序数据存储名称

返回值

类型	说明
DataStoreInfo	被恢复集合的信息对象

恢复文档验证专用 OrderedDataStore

-- @runtime client
local service = editor:GetService("DataStoreService")
local Task = editor:GetService("Task")
Task:Spawn(function()
    local info = service:RestoreOrderedDataStoreAsync("DocumentationSandboxOrdered")
    print("恢复结果:", info)
end)