工坊手册

主题

ConfigSnapshot ​

概览 ​

字段值
KindUnit · 单位 Unit
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • [ConfigSnapshot]（1 属性 / 3 函数 / 1 事件）

继承成员 ​

1 个来源 / 4 属性 / 25 函数 / 6 事件

ConfigSnapshot 是由 ConfigService 获取的不可变配置视图，可读取键值、监听单键变化，并在后台版本更新后主动刷新。

适用场景 ​

服务端获取全局或玩家配置后，用快照驱动业务参数，并在 UpdateAvailable 到达时刷新到最新已发布版本。

使用要点 ​

先通过服务端 ConfigService:GetConfigAsync() 或 GetConfigForPlayerAsync() 获取快照；使用 GetValue 读取键，使用 GetValueChangedSignal 监听值变化，收到 UpdateAvailable 后调用 Refresh。

注意事项 ​

ConfigSnapshot 不可自行构造；其获取入口 ConfigService 的 realm 为 server，因此示例均在服务端运行。快照不会静默替换创建时的数据，需在 Outdated/UpdateAvailable 提示后显式 Refresh。

代码示例 ​

读取配置并在版本更新时刷新 ​

lua
-- @runtime server
local Task = game:GetService('Task')
local ConfigService = game:GetService('ConfigService')
Task:Spawn(function()
    local snapshot = ConfigService:GetConfigAsync()
    print('配置值:', snapshot:GetValue('attack'))
    snapshot.UpdateAvailable:Once(function()
        snapshot:Refresh()
        print('配置已刷新:', snapshot:GetValue('attack'))
    end)
end)

属性 (1) ​

Name类型默认值说明
OutdatedBoolfalseOutdated 是 ConfigSnapshot 上的一个只读 Bool 属性，用于标识当前配置快照是否已过期。读取该属性即可得到快照的过期状态，它不返回具体的配置内容，只反映快照本身与最新配置之间的新旧关系。

关联类型 ​

事件 (1) ​

UpdateAvailable ​

签名：UpdateAvailable() 触发：local

ConfigSnapshot 的 UpdateAvailable 事件在后端版本发生变化时触发一次，通常对应快照的 Outdated 由 false 变为 true。

示例代码

收到新版本后刷新快照

lua
-- @runtime server
local Task = game:GetService('Task')
Task:Spawn(function()
    local snapshot = game:GetService('ConfigService'):GetConfigAsync()
    snapshot.UpdateAvailable:Once(function()
        snapshot:Refresh()
        print('已同步最新配置')
    end)
end)

函数 (3) ​

GetValue ​

签名：GetValue(key: String) -> Any (配置值)

获取指定配置项的值；优先返回试玩覆盖值，未命中覆盖时返回快照锁定的值。

参数类型说明
keyString配置键名

返回值 Any (配置值)

示例代码

读取配置项

lua
-- @runtime server
local Task = game:GetService('Task')
Task:Spawn(function()
    local snapshot = game:GetService('ConfigService'):GetConfigAsync()
    local value = snapshot:GetValue('attack')
    print('attack:', value)
end)

GetValueChangedSignal ​

签名：GetValueChangedSignal(key: String) -> Signal (变更信号)

GetValueChangedSignal 用于取得 ConfigSnapshot 上某个 key 的变更信号：传入字符串类型的 key，返回对应的 Signal 对象，该信号按 key 获取或懒创建。当 Refresh 检测到该 key 的值发生变化，或 SetTestingValue、ClearTestingValue 的调用影响到该 key 时，信号会以 Fire(newValue, oldValue) 的形式触发，把新值与旧值一并带出。借助它可以把「配置变化后再处理」写成事件驱动的逻辑，而不必持续轮询比对。

参数类型说明
keyString配置键名

返回值 Signal (变更信号)

示例代码

监听配置项变化

lua
-- @runtime server
local Task = game:GetService('Task')
Task:Spawn(function()
    local snapshot = game:GetService('ConfigService'):GetConfigAsync()
    snapshot:GetValueChangedSignal('attack'):Once(function(newValue, oldValue)
        print('attack 变化:', oldValue, '->', newValue)
    end)
end)

Refresh ​

签名：Refresh() -> void

主动同步到最新已发布配置；同步完成后快照的 Outdated 复位为 false。

返回值 void

示例代码

刷新过期快照

lua
-- @runtime server
local Task = game:GetService('Task')
Task:Spawn(function()
    local snapshot = game:GetService('ConfigService'):GetConfigAsync()
    if snapshot.Outdated then
        snapshot:Refresh()
    end
    print('快照是否过期:', snapshot.Outdated)
end)