Godot 成就进度缓存：平台弹杯之前，客户端也要知道走到哪一步

平台成就经常被当成发布末期的小功能：达成条件时调用平台 SDK，弹杯就结束。可玩家体验不只发生在弹杯那一刻。很多成就是累积型，比如击败 100 个敌人、收集 50 个图鉴、完成 10 次挑战。客户端需要知道当前进度，离线时也要记录，平台提交失败后要重试，UI 还要显示“差一点完成”。

Godot 项目如果把成就判断散在玩法脚本里，很容易重复解锁、漏统计或平台状态不同步。更稳的做法是建立 AchievementProgressService，让玩法只提交统计事件，服务负责进度、条件、平台提交和快照展示。

项目里的真实问题

一次桌面版本测试中，玩家离线完成了“击败 100 个敌人”，游戏内提示已达成，但重新联网后平台没有弹杯。另一个问题是同一成就被多个场景重复提交，平台 SDK 返回 already_unlocked，但客户端仍然反复弹本地 Toast。累积进度还存在存档回滚问题：玩家读旧档后，成就进度是否回退？

这些问题说明成就不是简单回调。它需要本地进度缓存、不可逆解锁记录、平台同步状态和统计事件去重。

设计目标

• 进度可见：客户端能展示累积成就当前进度和完成状态。
• 离线可靠：离线达成后记录待同步，联网后提交平台。
• 重复安全：同一成就不会反复本地弹出或反复提交危险状态。
• 统计清晰：玩法提交事件，成就系统统一计算条件。

这些目标不是为了堆抽象，而是为了让 Godot 客户端在内容量增加、平台差异变多、团队协作变复杂之后仍然可维护。原型阶段直接在节点脚本里写判断很快，但进入发版节奏后，系统需要能解释当前状态、能处理失败、能被 QA 复现，也能被后续同事接手。

推荐架构

flowchart TD
    A["玩法统计/平台回调"] --> B["AchievementProgressService"]
    B --> C["本地进度"]
    B --> D["解锁条件"]
    B --> E["平台提交"]
    B --> F["离线同步"]
    C --> G["状态快照"]
    D --> G
    E --> G
    F --> G
    G --> H["UI反馈/日志/回滚"]

图里的模块可以按项目规模合并。小团队可以先用一个 Autoload 管理核心状态，大团队再拆成 Resource 配置、运行时服务、调试面板和 UI ViewModel。真正重要的是调用方向：场景和 UI 不直接修改底层状态，而是提交意图并订阅快照。

关键实现细节

AchievementDefinition 包含 id、platform_id、type、target_value、stat_key、hidden、reward、sync_policy。累积型成就用 stat_key 统计，事件型成就直接达成。定义版本变更时，要考虑旧进度如何迁移。
统计事件应尽量语义化，例如 enemy_killed、chapter_completed、item_collected。玩法系统不直接判断成就是否完成，只提交事件和上下文。服务根据定义更新进度。
解锁记录应不可逆。即使玩家读旧档，已解锁成就一般不应回退。进度型成就是否回退要看设计，通常平台成就进度不回退，本地 UI 可以显示已完成。
平台提交失败时，记录 pending_sync。下次联网或启动时重试。平台返回 already_unlocked 时，本地标记为 synced，不再弹本地完成提示。

失败处理和恢复路径

平台 SDK 未初始化时，成就进度仍应本地记录，不直接丢弃。
成就定义删除或 platform_id 变化时，要保留本地历史并记录迁移。
统计事件爆发时要限流和聚合，避免每杀一个敌人都同步平台。

数据契约和协作接口

玩法系统提交 AchievementStatEvent，包含 stat_key、delta、context 和 timestamp。
AchievementProgressSnapshot 包含 id、value、target、unlocked、synced、pending_reason。
UI 成就面板订阅快照，不直接读平台 SDK。

GDScript 接口草图

class_name AchievementProgressService
extends Node

signal snapshot_changed(snapshot: Dictionary)
signal warning_raised(code: String, detail: Dictionary)

var _snapshot := {}
var _active_version := 0

func submit(intent: Dictionary) -> void:
    _active_version += 1
    var version := _active_version
    _snapshot = {"phase": "pending", "intent": intent, "system": "godot-achievement-progress-cache-2026"}
    emit_signal("snapshot_changed", _snapshot)
    _resolve(intent, func(result: Dictionary):
        if version != _active_version:
            return
        if result.get("warning", "") != "":
            emit_signal("warning_raised", result.warning, result)
        _snapshot = result
        emit_signal("snapshot_changed", _snapshot)
    )

func current_snapshot() -> Dictionary:
    return _snapshot.duplicate(true)

接口草图展示的是系统边界，不是完整实现。真实项目里还要补超时、取消、错误码、日志字段和平台差异。保留版本号，是为了避免旧异步结果覆盖新状态。

分阶段落地

第一阶段接入本地成就定义、统计事件和进度面板。
第二阶段加入平台提交、离线 pending 和重复解锁保护。
第三阶段处理定义迁移、隐藏成就和云存档对账。

自动化验证和人工验收

离线达成成就后重启并联网，确认平台提交成功。
重复触发同一完成事件，不重复弹 Toast。
平台返回 already_unlocked，本地标记 synced。
定义版本升级后，旧进度能迁移或保留。

观测指标

• 成就进度事件数量和处理耗时。
• pending_sync 数量和最长等待时间。
• 平台提交成功率和失败原因。
• 重复解锁被抑制次数。

指标不一定全部进入正式服。开发包可以显示完整调试面板，内测包采样关键计数，正式包只保留错误码和聚合趋势。指标的目的不是制造报表，而是让一次异常能被定位到具体阶段、具体配置和具体玩家路径。

上线前检查清单

• 玩法不直接调用平台成就接口。
• 本地记录进度、解锁和同步状态。
• 离线达成有 pending_sync。
• 平台 already_unlocked 能收敛为成功。
• 成就定义变更有迁移策略。

检查清单不是为了增加流程负担，而是把隐性经验写下来。能自动化的尽量交给脚本，不能自动化的也要明确谁在什么阶段确认。

案例复盘

一次离线测试中，玩家完成挑战后本地弹出成就，但平台未同步。接入 pending_sync 后，服务在联网恢复时提交 platform_id，并把状态从 unlocked_local 改为 synced。玩家不再需要重复挑战，客服也能从日志看到达成时间和同步时间。

灰度验收脚本

灰度验收准备三类成就：事件型、累积型、隐藏型。分别测试离线达成、重复达成、平台失败和 already_unlocked。验收时检查本地面板、Toast、平台弹杯和日志是否一致。

维护策略

成就上线后，新增玩法统计必须先注册 stat_key。不要让每个系统随便发字符串。成就定义最好有内容 owner，负责目标值、隐藏状态和迁移说明。

工程补充

成就系统还要区分展示进度和平台进度。某些平台只支持最终解锁，不支持中间进度；客户端仍然可以显示本地进度。若平台进度提交失败，本地进度不应回退。反过来，如果平台已经解锁但本地没有记录，启动对账时应把本地标记为已解锁，避免玩家看到矛盾状态。

这个系统落地后，配置版本要进入日志和问题反馈。无论是停顿规则、地表定义、高亮样式、配方表、成就定义还是占位策略，只要配置能影响玩家体验，就应该有版本号。线上反馈如果只知道“高亮不对”或“脚步声错了”，但不知道玩家用的是哪版配置，排查会非常慢。

调试面板也要尽早准备。开发包里至少能看到当前输入意图、系统决策、最终快照、失败原因和配置来源。对于表现类系统，最好能在画面上叠加当前 id：surface_id、highlight source、recipe_id、achievement_id、boss_phase。QA 截图带上这些信息，开发就能少猜很多。

协作与内容接入

这类系统大多需要内容同学持续接入。新增地表、新增配方、新增成就、新增 Boss 阶段、新增高亮样式，都不应该只改一个资源路径。每种新增内容都要有最小样本和验收步骤。样本可以很小，但必须能触发主要路径和失败路径。

建议把接入说明写成三段：需要填哪些字段，常见错误是什么，如何在调试模式验证。文档不必冗长，但要足够具体。例如“新增配方必须提供 recipe_version、result_preview、server_quote_policy”，比“记得配置完整”有用得多。

边界和降级

降级策略要提前写清楚。HitStop 异常时可以跳过停顿但保留伤害；脚步 Surface 缺失时用默认脚步；高亮样式缺失时用低强度默认描边；制作 quote 失败时禁用制作按钮；成就平台同步失败时保留本地 pending；截图隐私处理失败时阻断公开分享。不同系统的降级不一样，不能统一成“出错请重试”。

降级也要进入指标。fallback 次数长期偏高，说明内容或配置质量有问题。运行时兜底是保护玩家路径，不是让错误长期存在。每周看一次 fallback 排行，比发版前临时大扫除更有效。

灰度补充

灰度时还要专门验证“平台慢于本地”的场景。玩家本地已经达成并看到完成提示，但平台 SDK 初始化晚了十秒。UI 应显示本地已完成，后台等待同步；同步成功后不再弹第二次完成提示。若平台失败，状态保持 pending_sync 并允许下次启动继续提交。这个路径能证明本地体验和平台状态不会互相拖垮。

另外，成就面板要能展示隐藏成就的安全信息。未解锁隐藏成就只显示“隐藏成就”，但调试模式可以看到 achievement_id 和当前进度。正式 UI 保护惊喜，开发工具保留排查能力。

小团队接入版本

小团队可以先做本地进度缓存，再接平台 SDK。只要玩法事件先统一，平台接入只是同步层。不要在技能或关卡脚本里散落平台调用。

交付边界

交付标准是玩家能看到进度，离线达成不会丢，平台同步失败可恢复。成就系统的可靠性来自本地状态和平台状态能对账。

结语

平台弹杯只是成就系统的最后一步。Godot 客户端先把进度、解锁和同步状态管理好，成就体验才会稳定，玩家也能知道自己离目标还有多远。