主题
DataStore
DataStore 数据存储服务，通过 GetDataStore / GetGlobalDataStore 等获取。
概览
DataStore 是面向键值数据的持久化存储接口，负责将游戏数据按字符串键写入云端并读回，同时提供数值原子自增、按版本号或指定时间点回溯数据、分页枚举键列表与版本历史，以及删除键和清理历史版本等能力。它常作为存档、计数器和配置数据的落点，由数据存储服务统一分发，供各玩法模块存取。
不可实例化，由接口返回
函数
GetAsync
签名：GetAsync(key: String, options: DataStoreGetOptions?)
从数据存储中读取指定 key 对应的数据。若 key 不存在或数据已被删除，将返回 nil。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
options | DataStoreGetOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreGetOptions.New() 创建 |
读取玩家数据
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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?)
将指定 key 的数据设置为传入的 value，写入成功后返回该次写入对应的版本号。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
value | Any | 数据值 |
options | DataStoreSetOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreSetOptions.New() 创建 |
写入玩家数据
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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?)
对指定 key 存储的数值执行原子自增操作，并将自增后的值写回存储。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
delta | Int | 自增值 (非零) |
options | DataStoreIncrementOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreIncrementOptions.New() 创建 |
原子自增计数
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
Task:Spawn(function()
store:IncrementAsync('login_count', 1) -- delta 必须非零
end)RemoveAsync
签名：RemoveAsync(key: String, options: DataStoreRemoveOptions?)
删除数据存储中指定 key 及其当前数据，并返回被删除的数据内容。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
options | DataStoreRemoveOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreRemoveOptions.New() 创建 |
删除玩家数据
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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)
对指定 key 执行先读后写的复合更新操作：通过 transformFunction 基于当前值计算新值，再写回存储并返回更新结果。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
transformFunction | Function | 变换函数 function(currentValue, keyInfo) -> newValue, DataStoreSetOptions?; 返回 newValue=nil 时放弃更新; 可返回 DataStoreSetOptions 自定义写入选项 (如 metas, userIds); 每轮重试都会重新调用 transformFunction 拿到最新值 |
读-改-写原子更新
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor:GetService('Task')
local store = DataStoreService:GetDataStore('PlayerBackpack')
local playerId = 'demo-player'
Task:Spawn(function()
store:UpdateAsync('player_' .. playerId, function(oldValue, keyInfo)
oldValue = oldValue or {coins=0}
oldValue.coins = oldValue.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 client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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?)
按版本号读取指定 key 的历史版本；options 可省略，也可通过 DataStoreGetVersionOptions.New() 创建。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
version | String | 版本号 |
options | DataStoreGetVersionOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreGetVersionOptions.New() 创建 |
按版本号读取历史数据
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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?)
按时间点读取指定 key 在该时间附近的历史版本；options 可省略，也可通过 DataStoreGetVersionOptions.New() 创建。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
timestamp | Int | 时间戳 (毫秒) |
options | DataStoreGetVersionOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreGetVersionOptions.New() 创建 |
按时间点读取历史数据
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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 的历史版本信息，返回 DataStoreVersionInfoPages 分页对象。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
ascending | Bool | 排序方向, true 时按版本更新时间升序, false 时降序 |
minDate | Int | 最小时间 (毫秒) |
maxDate | Int | 最大时间 (毫秒) |
pageSize | Int | 页大小, 默认 0 (使用服务端默认值) |
返回值 DataStoreVersionInfoPages — 分页的版本信息列表，通过迭代器逐页获取
列出指定键的历史版本
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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?)
删除指定 key 的历史版本；options 可省略，也可通过 DataStoreRemoveVersionOptions.New() 创建。
| 参数 | 类型 | 说明 |
|---|---|---|
key | String | 键名 |
version | String | 版本号 |
options | DataStoreRemoveVersionOptions | 可选参数, 优先级高于 DataStore 创建时的 DataStoreOptions, 可通过 DataStoreRemoveVersionOptions.New() 创建 |
删除指定历史版本
lua
-- @runtime client
local DataStoreService = editor:GetService('DataStoreService')
local Task = editor: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)