主题
DataStore
数据存储集合，用于在服务端持久化保存键值对数据，支持按键读取、写入、自增、原子更新与删除，并提供键列表遍历和历史版本查询、清理能力。它无法自行创建，只能由 DataStoreService:GetDataStore()、GetGlobalD...
概览
数据存储集合，用于在服务端持久化保存键值对数据，支持按键读取、写入、自增、原子更新与删除，并提供键列表遍历和历史版本查询、清理能力。它无法自行创建，只能由 DataStoreService:GetDataStore()、GetGlobalDataStore() 或 GetOrderedDataStore() 返回，是操作某一份持久化存储的入口对象。
不可实例化，由接口返回
函数
GetAsync
签名：GetAsync(key: String, options: DataStoreGetOptions?) -> Any, DataStoreKeyInfo
GetAsync 按 key 读取 DataStore 中当前存储的数据值。参数 key 为字符串键名，可选参数 options 为 DataStoreGetOptions，用于描述本次读取的选项。返回值为数据值本体，当 key 不存在时返回 nil；当 options 中开启 WithKeyInfo 时，第二个返回值给出 DataStoreKeyInfo 键信息。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
options | DataStoreGetOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreGetOptions.New() 创建 |
返回值 Any value — 数据值, key 不存在时返回 nil；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
读取玩家数据
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local playerId = 'demo-player'
Task:Spawn(function()
local data = store:GetAsync('player_' .. playerId) -- 必须传 key
print('读取到:', data)
end)SetAsync
签名：SetAsync(key: String, value: Any, options: DataStoreSetOptions?) -> String, DataStoreKeyInfo
SetAsync 将数据值写入指定 key。参数 key 为字符串键名，value 为要写入的数据，第三个可选参数 options 为 DataStoreSetOptions。返回值为本次写入产生的版本号字符串；当 options 中开启 WithKeyInfo 时，第二个返回值给出 DataStoreKeyInfo 键信息。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
value | Any | 数据值 |
options | DataStoreSetOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreSetOptions.New() 创建 |
返回值 String version — 版本号；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
写入玩家数据
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local playerId = 'demo-player'
Task:Spawn(function()
store:SetAsync('player_' .. playerId, {coins=100, level=1})
end)IncrementAsync
签名：IncrementAsync(key: String, delta: Int, options: DataStoreIncrementOptions?) -> Any, DataStoreKeyInfo
IncrementAsync 对指定 key 的数值执行原子自增。参数 key 为字符串键名，delta 为整数增量，第三个可选参数 options 为 DataStoreIncrementOptions。返回值为自增后的值；当 options 中开启 WithKeyInfo 时，第二个返回值给出 DataStoreKeyInfo 键信息。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
delta | Int | 自增值 (非零) |
options | DataStoreIncrementOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreIncrementOptions.New() 创建 |
返回值 Any value — 自增后的值；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
原子自增计数
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
Task:Spawn(function()
store:IncrementAsync('login_count', 1) -- delta 必须非零
end)RemoveAsync
签名：RemoveAsync(key: String, options: DataStoreRemoveOptions?) -> Any, DataStoreKeyInfo
RemoveAsync 删除指定 key 所存储的数据。参数 key 为字符串键名，可选参数 options 为 DataStoreRemoveOptions。返回值为删除前的数据值，key 不存在时返回 nil；当 options 中开启 WithKeyInfo 时，第二个返回值给出 DataStoreKeyInfo 键信息。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
options | DataStoreRemoveOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreRemoveOptions.New() 创建 |
返回值 Any value — 删除前的数据值, key 不存在时返回 nil；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
删除玩家数据
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local options = DataStoreRemoveOptions.New()
options.WithKeyInfo = true
Task:Spawn(function()
local removedValue, keyInfo = store:RemoveAsync('player_demo', options)
print('删除值:', removedValue, '版本:', keyInfo and keyInfo.Version)
end)UpdateAsync
签名：UpdateAsync(key: String, transformFunction: Function) -> Any, DataStoreKeyInfo
对指定键执行先读后写的复合更新操作：调用时传入键名 key 与转换函数 transformFunction，由转换函数基于该键的当前值计算出要写回的新值；调用返回更新后的值以及键信息 DataStoreKeyInfo，当转换函数放弃更新时返回值中的值为 nil。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
transformFunction | Function | 变换函数 function(currentValue, keyInfo) -> newValue, DataStoreSetOptions?; 返回 newValue=nil 时放弃更新; 可返回 DataStoreSetOptions 自定义写入选项 (如 metas, userIds); 每轮重试都会重新调用 transformFunction 拿到最新值 |
返回值 Any value — 更新后的值, 放弃更新时返回 nil；DataStoreKeyInfo keyInfo — 键信息
读-改-写原子更新
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local playerId = 'demo-player'
Task:Spawn(function()
store:UpdateAsync('player_' .. playerId, function(oldValue, keyInfo)
if type(oldValue) ~= 'table' then return {coins=50} end
local coins = tonumber(oldValue.coins) or 0
oldValue.coins = coins + 50
return oldValue -- 返回 nil 放弃更新
end)
end)ListKeysAsync
签名：ListKeysAsync(prefix: String?, pageSize: Int?, cursor: String?, options: DataStoreListKeyOptions?) -> DataStoreKeyBriefInfoPages
分页列出数据存储中的 key，支持按前缀过滤。
| 参数 | 类型 | 说明 |
|---|---|---|
prefix | String? | 前缀过滤, 默认空字符串 |
pageSize | Int? | 页大小, 默认 0 (使用服务端默认值) |
cursor | String? | 分页游标 |
options | DataStoreListKeyOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreListKeyOptions.New() 创建 |
返回值 DataStoreKeyBriefInfoPages
分页列出键名
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local options = DataStoreListKeyOptions.New()
options.ExcludeDeleted = false
Task:Spawn(function()
local pages = store:ListKeysAsync('player_', 10, '', options)
for _, keyInfo in ipairs(pages:GetCurrentPage()) do
print('键名:', keyInfo.Key)
end
end)GetVersionAsync
签名：GetVersionAsync(key: String, version: String, options: DataStoreGetVersionOptions?) -> Any, DataStoreKeyInfo
按版本号读取指定 key 的历史版本；options 可省略，也可通过 DataStoreGetVersionOptions.New() 创建。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
version | String | 版本号 |
options | DataStoreGetVersionOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreGetVersionOptions.New() 创建 |
返回值 Any value — 数据值, 版本或 key 不存在时返回 nil；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
按版本号读取历史数据
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local key = 'player_demo'
Task:Spawn(function()
local pages = store:ListVersionsAsync(key, false, 0, 0, 10)
local versionInfo = pages:GetCurrentPage()[1]
if versionInfo == nil then
print('当前键没有可读取的历史版本')
return
end
local value = store:GetVersionAsync(key, versionInfo.Version)
print('历史版本数据:', value)
end)GetVersionAtTimeAsync
签名：GetVersionAtTimeAsync(key: String, timestamp: Int, options: DataStoreGetVersionOptions?) -> Any, DataStoreKeyInfo
按时间点读取指定 key 在该时间附近的历史版本；options 可省略，也可通过 DataStoreGetVersionOptions.New() 创建。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
timestamp | Int | 时间戳 (毫秒) |
options | DataStoreGetVersionOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreGetVersionOptions.New() 创建 |
返回值 Any value — 数据值, 该时间点无对应版本时返回 nil；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
按时间点读取历史数据
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local key = 'player_demo'
local timestamp = 1700000000 * 1000
Task:Spawn(function()
local value = store:GetVersionAtTimeAsync(key, timestamp)
print('指定时间附近的数据:', value)
end)ListVersionsAsync
签名：ListVersionsAsync(key: String, ascending: Bool?, minDate: Int?, maxDate: Int?, pageSize: Int?) -> DataStoreVersionInfoPages
列出指定 key 的所有历史版本信息。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
ascending | Bool? | 排序方向, true 时按版本更新时间升序, false 时降序 |
minDate | Int? | 最小时间 (毫秒) |
maxDate | Int? | 最大时间 (毫秒) |
pageSize | Int? | 页大小, 默认 0 (使用服务端默认值) |
返回值 DataStoreVersionInfoPages
列出指定键的历史版本
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
Task:Spawn(function()
local pages = store:ListVersionsAsync('player_demo', false, 0, 0, 10)
for _, versionInfo in ipairs(pages:GetCurrentPage()) do
print('版本:', versionInfo.Version, '创建时间:', versionInfo.CreatedTime)
end
end)RemoveVersionAsync
签名：RemoveVersionAsync(key: String, version: String, options: DataStoreRemoveVersionOptions?) -> Any, DataStoreKeyInfo
删除指定 key 的历史版本；options 可省略，也可通过 DataStoreRemoveVersionOptions.New() 创建。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
version | String | 版本号 |
options | DataStoreRemoveVersionOptions? | 可选参数, 优先级高于 DataStore 初始化时的 DataStoreOptions, 可通过 DataStoreRemoveVersionOptions.New() 创建 |
返回值 Any value — 删除前的数据值, 版本不存在时返回 nil；DataStoreKeyInfo keyInfo — 键信息 (需 WithKeyInfo=true 才会返回)
删除指定历史版本
lua
-- @runtime server
local DataStoreService = game:GetService('DataStoreService')
local Task = game:GetService('Task')
local store = DataStoreService:GetDataStore('DocumentationSandbox')
local key = 'cleanup_demo'
Task:Spawn(function()
local pages = store:ListVersionsAsync(key, false, 0, 0, 10)
local versionInfo = pages:GetCurrentPage()[1]
if versionInfo == nil then
print('当前键没有可删除的历史版本')
return
end
-- 仅在确认该沙盒版本可以删除后执行
local removedValue = store:RemoveVersionAsync(key, versionInfo.Version)
print('删除的版本数据:', removedValue)
end)