工坊手册

主题

ArchiveService ​

概览 ​

字段值
KindService · 服务 Service
Realmserver

ArchiveService 是服务端的存档与成就服务，负责按玩家读写自定义存档数据，并管理成就的进度、目标数量、奖励与完成状态。它同时提供按名称或成就编号查询存档编号的接口，让脚本可以在自定义键值与已配置成就之间建立映射。当成就达成或奖励发放时，服务会发出本地信号，便于服务端做后续结算与提示。

适用场景 ​

适合在服务端实现玩家个人进度、关卡解锁、累计计数一类玩法：用自定义存档保存长期数据，用成就接口累计进度并在达成时发放奖励。也常用于在玩家加入或行为结算时读取存档、写回最新进度，并监听成就达成信号做一次性的奖励处理。

使用要点 ​

在服务端通过 game:GetService("ArchiveService") 获取实例。GetCustomArchiveIdByName 与 GetCustomArchiveIdByAchievementId 可查询存档键；GetCustomArchive/SetCustomArchive 按键读写，GetCustomArchiveByName/SetCustomArchiveByName 按名称读写。使用 GetAchievementProgress、SetAchievementProgress、AddAchievementProgress 管理进度，并以 IsAchievementCompleted 查询状态。AchievementComplete 与 AchievementRewardGain 用于获知成就达成及奖励已领取，回调里可更新提示或日志；奖励发放应遵循业务流程，避免重复发放。

注意事项 ​

ArchiveService 是服务端存档与成就服务，需在服务端脚本中获取并调用。eventId 必须是已配置的成就 ID，运行时会校验，调用时建议用 pcall 保护。AchievementComplete 和 AchievementRewardGain 的事件标记为 local，表示当前服务实例上的本地信号作用域，不表示客户端事件；监听示例应放在服务端。

代码示例 ​

监听成就完成事件并读取进度 ​

lua
-- @runtime server
local archiveService = game:GetService('ArchiveService')

archiveService.AchievementComplete:Once(function(player, eventId)
    local progress = archiveService:GetAchievementProgress(player, eventId)
    local targetCount = archiveService:GetAchievementTargetCount(eventId)
    print('成就完成:', player:GetName(), eventId, progress, targetCount)
end)

事件 (2) ​

AchievementComplete ​

签名：AchievementComplete(player: Player, eventId: Int) 触发：local

成就完成事件。当某个玩家的某项成就被判定为完成时触发，回调参数依次为玩家对象 player（Player）与该成就对应的事件 ID eventId（Int）。

回调参数类型说明
playerPlayer玩家
eventIdInt成就id

示例代码

监听成就完成事件

lua
-- @runtime server
local archiveService = game:GetService('ArchiveService')
archiveService.AchievementComplete:Once(function(player, eventId)
    local progress = archiveService:GetAchievementProgress(player, eventId)
    print('成就完成:', player:GetName(), eventId, progress)
end)

AchievementRewardGain ​

签名：AchievementRewardGain(player: Player, eventId: Int) 触发：local

成就领取奖励事件。当玩家领取某项成就对应的奖励时触发，回调参数依次为玩家对象 player（Player）与该成就对应的事件 ID eventId（Int）。

回调参数类型说明
playerPlayer玩家
eventIdInt成就id

示例代码

监听成就奖励领取事件

lua
-- @runtime server
local archiveService = game:GetService('ArchiveService')
archiveService.AchievementRewardGain:Once(function(player, eventId)
    print('成就奖励已领取:', player:GetName(), eventId)
end)

函数 (14) ​

GetCustomArchiveIdByName ​

签名：GetCustomArchiveIdByName(name: String) -> Int (自定义存档id)

通过名称获取自定义存档的 ID。

参数类型说明
nameString自定义存档名称

返回值 Int (自定义存档id)

示例代码

按业务配置解析存档 ID

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function resolveArchiveId(archiveName)
    if archiveName == nil or archiveName == "" then return nil end
    return archiveService:GetCustomArchiveIdByName(archiveName)
end
-- archiveName 应来自当前地图的真实存档配置

GetCustomArchiveIdByAchievementId ​

签名：GetCustomArchiveIdByAchievementId(eventId: Int) -> Int (自定义存档id)

通过成就 ID 获取关联的自定义存档 ID。

参数类型说明
eventIdInt成就id

返回值 Int (自定义存档id)

示例代码

按已配置成就查询关联存档

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function resolveArchiveIdByAchievement(configuredEventId)
    return pcall(function()
        return archiveService:GetCustomArchiveIdByAchievementId(configuredEventId)
    end)
end
-- 在业务流程中传入已配置的成就 ID

GetAchievementTargetCount ​

签名：GetAchievementTargetCount(eventId: Int) -> Int (目标次数)

获取指定成就的目标完成次数。

参数类型说明
eventIdInt成就id

返回值 Int (目标次数)

示例代码

查询已配置成就的目标次数

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function getTargetCount(configuredEventId)
    return pcall(function()
        return archiveService:GetAchievementTargetCount(configuredEventId)
    end)
end
-- 在业务流程中传入已配置的成就 ID

GetAchievementAutoGain ​

签名：GetAchievementAutoGain(eventId: Int) -> Bool (自动领取)

查询指定成就的奖励是否设置为自动领取。

参数类型说明
eventIdInt成就id

返回值 Bool (自动领取)

示例代码

查询已配置成就是否自动领奖

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function isAutoGain(configuredEventId)
    return pcall(function()
        return archiveService:GetAchievementAutoGain(configuredEventId)
    end)
end
-- 在业务流程中传入已配置的成就 ID

GetAchievementIsSingle ​

签名：GetAchievementIsSingle(eventId: Int) -> Bool (单局成就)

查询指定成就是否为单局成就。

参数类型说明
eventIdInt成就id

返回值 Bool (单局成就)

示例代码

查询已配置成就是否为单局成就

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function isSingleAchievement(configuredEventId)
    return pcall(function()
        return archiveService:GetAchievementIsSingle(configuredEventId)
    end)
end
-- 在业务流程中传入已配置的成就 ID

GetAchievementRewards ​

签名：GetAchievementRewards(eventId: Int) -> Map (奖励数据)

获取指定成就的奖励数据。

参数类型说明
eventIdInt成就id

返回值 Map (奖励数据)

示例代码

查询已配置成就的奖励数据

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function getAchievementRewards(configuredEventId)
    return pcall(function()
        return archiveService:GetAchievementRewards(configuredEventId)
    end)
end
-- 在业务流程中传入已配置的成就 ID

GetCustomArchive ​

签名：GetCustomArchive(player: Player, key: Int) -> Any (存档内容)

读取指定玩家以整数 key 存储的自定义存档内容。参数依次为玩家对象 player（Player）与存档 key（Int），返回类型为 Any 的存档内容。

参数类型说明
playerPlayer玩家
keyInt存档id

返回值 Any (存档内容)

示例代码

按业务传入的存档键读取数据

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function loadArchive(player, archiveKey)
    if player == nil or archiveKey == nil then return nil end
    return archiveService:GetCustomArchive(player, archiveKey)
end
-- archiveKey 应来自当前地图的真实存档配置

SetCustomArchive ​

签名：SetCustomArchive(player: Player, key: Int, value: Any) -> void

为指定玩家写入自定义存档。参数依次为玩家对象 player（Player）、存档 key（Int）与存档内容 value（Any），该函数无返回值。

参数类型说明
playerPlayer玩家
keyInt存档id
valueAny存档内容

返回值 void

示例代码

按业务传入的键写入自定义存档

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function saveArchive(player, archiveKey, value)
    -- player、archiveKey 和 value 由已校验的服务端业务流程传入
    archiveService:SetCustomArchive(player, archiveKey, value)
    return archiveService:GetCustomArchive(player, archiveKey)
end

GetCustomArchiveByName ​

签名：GetCustomArchiveByName(player: Player, name: String) -> Any (存档内容)

通过名称读取指定玩家的自定义存档内容。参数依次为玩家对象 player（Player）与存档名称 name（String），返回类型为 Any 的存档内容。

参数类型说明
playerPlayer玩家
nameString存档名称

返回值 Any (存档内容)

示例代码

按业务传入的存档名称读取数据

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function loadArchiveByName(player, archiveName)
    if player == nil or archiveName == nil or archiveName == "" then return nil end
    return archiveService:GetCustomArchiveByName(player, archiveName)
end
-- archiveName 应来自当前地图的真实存档配置

SetCustomArchiveByName ​

签名：SetCustomArchiveByName(player: Player, name: String, value: Any) -> void

通过名称写入指定玩家的自定义存档。参数依次为玩家对象 player（Player）、存档名称 name（String）与存档内容 value（Any），该函数无返回值。

参数类型说明
playerPlayer玩家
nameString存档名称
valueAny存档内容

返回值 void

示例代码

按业务传入的名称写入自定义存档

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function saveArchiveByName(player, archiveName, value)
    -- player、archiveName 和 value 由已校验的服务端业务流程传入
    archiveService:SetCustomArchiveByName(player, archiveName, value)
    return archiveService:GetCustomArchiveByName(player, archiveName)
end

GetAchievementProgress ​

签名：GetAchievementProgress(player: Player, eventId: Int) -> Int (进度)

获取指定玩家在指定成就上的当前进度。参数依次为玩家对象 player（Player）与成就事件 ID eventId（Int），返回值为 Int 类型的进度值。

参数类型说明
playerPlayer玩家
eventIdInt成就id

返回值 Int (进度)

示例代码

封装成就进度查询

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function getProgress(player, configuredEventId)
    local ok, progress = pcall(function()
        return archiveService:GetAchievementProgress(player, configuredEventId)
    end)
    return ok and progress or nil
end
-- 在业务流程中传入真实 Player 和已配置的成就 ID：getProgress(player, configuredEventId)

SetAchievementProgress ​

签名：SetAchievementProgress(player: Player, eventId: Int, count: Int) -> void

将指定玩家在指定成就上的进度直接设置为给定数值。参数依次为玩家对象 player（Player）、成就事件 ID eventId（Int）与进度值 count（Int），该函数无返回值。

参数类型说明
playerPlayer玩家
eventIdInt成就id
countInt成就进度

返回值 void

示例代码

封装成就进度设置

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function setProgress(player, configuredEventId, count)
    local ok, err = pcall(function()
        archiveService:SetAchievementProgress(player, configuredEventId, count)
    end)
    return ok, err
end
-- 在业务流程中传入真实 Player、已配置的成就 ID 和进度值。

AddAchievementProgress ​

签名：AddAchievementProgress(player: Player, eventId: Int, addCount: Int) -> void

为指定玩家在指定成就上累加进度。参数依次为玩家对象 player（Player）、成就事件 ID eventId（Int）与本次增加的进度值 addCount（Int），该函数无返回值。

参数类型说明
playerPlayer玩家
eventIdInt成就id
addCountInt增加的成就进度

返回值 void

示例代码

封装成就进度累加

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function addProgress(player, configuredEventId, addCount)
    local ok, err = pcall(function()
        archiveService:AddAchievementProgress(player, configuredEventId, addCount)
    end)
    return ok, err
end
-- 在业务流程中传入真实 Player、已配置的成就 ID 和增量。

IsAchievementCompleted ​

签名：IsAchievementCompleted(player: Player, eventId: Int) -> Bool (是否完成)

判断指定玩家在指定成就上是否已完成。参数依次为玩家对象 player（Player）与成就事件 ID eventId（Int），返回 Bool 表示是否完成。

参数类型说明
playerPlayer玩家
eventIdInt成就id

返回值 Bool (是否完成)

示例代码

封装成就完成状态查询

lua
-- @runtime server
local archiveService = game:GetService("ArchiveService")
local function isCompleted(player, configuredEventId)
    local ok, completed = pcall(function()
        return archiveService:IsAchievementCompleted(player, configuredEventId)
    end)
    return ok and completed or false
end
-- 在业务流程中传入真实 Player 和已配置的成就 ID。