ConfigService

概览

字段	值
Kind	Service · 服务 Service
Realm	server

继承关系

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

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

服务端配置服务，用于读取地图配置快照、按玩家读取配置，并在试玩模式下设置或清理临时测试值。

适用场景

适合服务端加载活动、数值或玩家分层配置，并在后台配置版本更新时刷新已有快照。

使用要点

仅在服务端通过 game:GetService("ConfigService") 获取服务；调用 GetConfigAsync 或 GetConfigForPlayerAsync 后在回调中处理 ConfigSnapshot，并根据 UpdateAvailable 或 Outdated 决定是否 Refresh。

注意事项

ConfigService 仅在服务端可用。GetConfigAsync 与 GetConfigForPlayerAsync 返回 ConfigSnapshot；快照不会在后台版本更新后静默替换数据，应监听 UpdateAvailable 或检查 Outdated，并按需调用 Refresh。SetTestingValue 与 ClearTestingValue 只在试玩模式生效，不会修改已发布配置。

代码示例

读取基础配置并按玩家获取覆盖快照

-- @runtime server
local Task = game:GetService("Task")
local Players = game:GetService("Players")
local configService = game:GetService("ConfigService")

Task:Spawn(function()
    local snapshot = configService:GetConfigAsync()
    if snapshot == nil then return end
    print("基础配置是否过期:", snapshot.Outdated)

    for _, player in ipairs(Players:GetPlayers()) do
        local playerSnapshot = configService:GetConfigForPlayerAsync(player)
        if playerSnapshot ~= nil then
            print(player:GetName(), "玩家配置是否过期:", playerSnapshot.Outdated)
        end
    end
end)

关联类型

• Unit

函数 (4)

GetConfigAsync

签名：GetConfigAsync() -> ConfigSnapshot (配置快照)

ConfigService 的异步方法，用于获取最新的已发布配置快照，返回一个 ConfigSnapshot 对象。该快照是读取具体配置值的入口，可通过 ConfigSnapshot 提供的读取能力获取关注的配置项。

返回值 ConfigSnapshot (配置快照)

示例代码

获取最新已发布配置快照并检查过期状态

-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    -- 配置服务仅服务端可用，先按公开路径获取服务实例
    local configService = game:GetService("ConfigService")

    -- 拉取最新已发布配置快照，返回 ConfigSnapshot 对象
    local snapshot = configService:GetConfigAsync()

    -- 消费返回值：打印快照本体与过期状态，确认当前拿到的版本可用
    print("已获取配置快照:", snapshot)
    print("快照是否已过期:", snapshot.Outdated)

    -- 快照可反复读取具体配置项，业务逻辑中无需重复拉取
    local value = snapshot:GetValue("int_value")
    print("int_value 当前取值:", value)
end)

GetConfigForPlayerAsync

签名：GetConfigForPlayerAsync(player: Player) -> ConfigSnapshot (配置快照（携带玩家分桶信息）)

GetConfigForPlayerAsync 是 ConfigService 提供的异步函数，用于获取面向指定玩家的配置快照。调用时需传入一个 Player 对象作为 player 参数，返回值为 ConfigSnapshot 类型的配置快照，该快照携带该玩家对应的分桶信息。

参数	类型	说明
player	Player	玩家对象

返回值 ConfigSnapshot (配置快照（携带玩家分桶信息）)

示例代码

在任务协程中读取玩家配置快照

-- @runtime server
local Task = game:GetService("Task")
local Players = game:GetService("Players")
local configService = game:GetService("ConfigService")
local player = Players:GetPlayers()[1]
if player == nil then return end

Task:Spawn(function()
    local snapshot = configService:GetConfigForPlayerAsync(player)
    if snapshot ~= nil then
        print("玩家配置是否过期:", snapshot.Outdated)
    end
end)

SetTestingValue

签名：SetTestingValue(key: String, value: Any) -> void

在试玩模式下临时覆盖指定 key 的配置值，用于本地测试不同配置效果。

参数	类型	说明
key	String	配置键名
value	Any	覆盖值

返回值 void

示例代码

设置测试覆盖值

-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    -- 获取 ConfigService 服务实例
    local configService = game:GetService("ConfigService")

    -- 在试玩模式下临时覆盖一个 key 的值
    configService:SetTestingValue("my_key", "test_value")

    -- 获取配置快照，验证覆盖是否生效
    local snapshot = configService:GetConfigAsync()
    local value = snapshot:GetValue("my_key")
    print("设置测试值后，my_key 的值为:", value)

    -- 清除测试覆盖，恢复原始值
    configService:ClearTestingValue("my_key")
end)

ClearTestingValue

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

清除指定 key 在试玩模式下临时覆盖的值，恢复为已发布配置的原始值。

参数	类型	说明
key	String	配置键名

返回值 void

示例代码

清除测试覆盖值

-- @runtime server
local Task = game:GetService("Task")
Task:Spawn(function()
    -- 获取 ConfigService 服务实例
    local configService = game:GetService("ConfigService")

    -- 先设置一个测试值，模拟试玩模式下的临时覆盖
    configService:SetTestingValue("my_key", "test_value")

    -- 清除该 key 的测试覆盖，恢复为原始配置值
    configService:ClearTestingValue("my_key")

    -- 验证清除后，通过快照读取该 key 的值（应为原始配置值）
    local snapshot = configService:GetConfigAsync()
    local value = snapshot:GetValue("my_key")
    print("清除测试值后，my_key 的值为:", value)
end)