《Steam 游戏平台:开发与商业化》3.1 成就机制

成就机制是 Steamworks 对玩家里程碑的标准建模:SetAchievement 解锁、GetAchievementAndUnlockTime 读状态与解锁时间、StoreStats 落库并产生 UserAchievementStored_t 新成就回调。本节讲成就接口的工程语义与解锁生命周期,lab 用 C++ 模拟解锁、查询、清除、进度与持久化回调。

3.1 成就机制

成就是玩家达成里程碑后由平台展示并持久化的标记。接入要回答的工程问题是:判定谁来做、持久化谁负责、展示走哪条通道。卷一在机制层讲过成就如何构成留存与社交货币;这一节落到 SDK 侧——判定逻辑始终在游戏代码里,Steamworks 负责把「已解锁」记到服务器,并在客户端以覆盖层 UI 展示。

本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamuserstats.h。

本章与站内既有内容的分工

  • Steam 发行专题 (操作手册)讲「后台如何创建成就、定义属性、测试解锁」;本节讲「代码里解锁成就的接口语义」。
  • 卷一《平台机制与商店》讲成就如何影响留存与商业;本节讲成就的工程生命周期——解锁、查询、持久化、回调。
  • lab 用纯 C++ 模拟成就状态机与 StoreStats 的新成就回调,不依赖 Steam 客户端运行。

解锁与查询

成就接口的第一组语义围绕状态读写:

// isteamuserstats.h:SetAchievement / GetAchievement / ClearAchievement(SDK v1.65 头文件摘录,已删减)
virtual bool SetAchievement( const char *pchName ) = 0;
virtual bool GetAchievement( const char *pchName, bool *pbAchieved ) = 0;
virtual bool ClearAchievement( const char *pchName ) = 0;
// isteamuserstats.h:GetAchievementAndUnlockTime(SDK v1.65 头文件摘录,已删减)
virtual bool GetAchievementAndUnlockTime( const char *pchName, bool *pbAchieved, uint32 *punUnlockTime ) = 0;

工程语义:

  1. 返回 bool 是「调用是否成功」,不是「是否已解锁」:SetAchievement 返回 false 通常表示成就在后台未配置或名字不合法;GetAchievement 把结果写到 pbAchieved 输出参数。
  2. GetAchievementAndUnlockTime 附带解锁时间:头文件注释明确——时间为 0 表示该成就在 2009 年 12 月(Steam 开始记录解锁时间)之前解锁。
  3. ClearAchievement 是复位通道:用于测试环境重置或开发期调试,生产逻辑很少主动清除已解锁成就。

持久化与新成就回调

解锁只是内存态,上服务器靠 StoreStats:

// isteamuserstats.h:StoreStats(SDK v1.65 头文件摘录,已删减)
// Store the current data on the server, will get a callback when set
// And one callback for every new achievement
virtual bool StoreStats() = 0;

回调结构:

// isteamuserstats.h:UserAchievementStored_t(SDK v1.65 头文件摘录,已删减)
struct UserAchievementStored_t
{
	enum { k_iCallback = k_iSteamUserStatsCallbacks + 3 };

	uint64		m_nGameID;				// Game this is for
	bool		m_bGroupAchievement;	// unused. if this is a "group" achievement
	char		m_rgchAchievementName[k_cchStatNameMax];		// name of the achievement
	uint32		m_nCurProgress;			// current progress towards the achievement
	uint32		m_nMaxProgress;			// "out of" this many
};

工程语义:

  1. StoreStats 把当前全部统计与成就状态推上服务器,成功后收到回调;每解锁一个新成就,就有一个 UserAchievementStored_t 回调(头文件注释明文)。
  2. 回调里的进度字段有特殊含义:m_nCurProgress/m_nMaxProgress 都为零,表示该成就已被完整解锁;非零表示进度型成就当前进度。
  3. 解锁必须先 SetAchievement 再 StoreStats:只 SetAchievement 不落库,服务器不知道;StoreStats 是成就与统计的持久化闸门。

元数据与进度提示

展示侧需要成就的元数据与枚举能力:

// isteamuserstats.h:GetAchievementDisplayAttribute / GetAchievementIcon / IndicateAchievementProgress / GetNumAchievements / GetAchievementName(SDK v1.65 头文件摘录,已删减)
virtual int GetAchievementIcon( const char *pchName ) = 0;
virtual bool IndicateAchievementProgress( const char *pchName, uint32 nCurProgress, uint32 nMaxProgress ) = 0;
virtual uint32 GetNumAchievements() = 0;
virtual const char *GetAchievementName( uint32 iAchievement ) = 0;

工程语义:

  1. 隐藏成就由显示属性控制:GetAchievementDisplayAttribute 接受 "name"/"desc"/"hidden" 等键,hidden 返回 "1"/"0";隐藏成就在解锁前不向玩家展示。
  2. IndicateAchievementProgress 只记进度、不自动解锁:它驱动覆盖层的「进度条」展示;解锁判定仍在游戏代码里(统计达标后由 SetAchievement 落地,见 3.3)。
  3. GetNumAchievements/GetAchievementName 提供枚举:用于成就列表 UI;头文件注释提醒,一般游戏应把成就清单编译进客户端,不应运行时依赖枚举。

接口签名对照

头文件条目语义
isteamuserstats.hISteamUserStats::SetAchievement解锁成就(内存态)
isteamuserstats.hGetAchievement/GetAchievementAndUnlockTime查询状态与解锁时间
isteamuserstats.hClearAchievement复位成就(测试用)
isteamuserstats.hStoreStats持久化到服务器,新成就触发回调
isteamuserstats.hUserAchievementStored_t新成就存储回调结构
isteamuserstats.hGetAchievementDisplayAttribute/GetAchievementIcon元数据与图标
isteamuserstats.hIndicateAchievementProgress进度提示(不自动解锁)
isteamuserstats.hGetNumAchievements/GetAchievementName成就枚举

数据口径与来源

  • 接口签名、回调结构字段(UserAchievementStored_t 的 k_iCallback、m_nCurProgress 等)、k_cchStatNameMax = 128:SDK v1.65 public/steam/isteamuserstats.h 可实证(本机镜像已核对)。
  • 「StoreStats 后收到回调、每个新成就一个回调」:isteamuserstats.h 顶部注释明文。
  • 「解锁时间为 0 表示 2009 年 12 月前解锁」:GetAchievementAndUnlockTime 注释明文。
  • 隐藏成就的展示策略、进度条 UI:以 partner 文档与 Steam 客户端表现为准,登录后可见数据以官方当前为准。

以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。

可运行产物:C++ 最小验证

下面的仿真复现「成就机制」的工程语义:解锁/查询/清除的完整状态机、隐藏成就属性、IndicateAchievementProgress 只记进度不自动解锁、StoreStats 持久化并产生 UserAchievementStored_t 新成就回调、成就枚举与图标句柄。它与 src/03-1-achievement-mechanics.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/03-1-achievement-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/03-1-achievement-mechanics.cpp -o bin/03-1-achievement-mechanics && ./bin/03-1-achievement-mechanics
//
// mock:复现成就机制的工程语义——SetAchievement/GetAchievement/
// GetAchievementAndUnlockTime/ClearAchievement、隐藏成就属性、
// IndicateAchievementProgress 只记进度不自动解锁、StoreStats 时的新成就回调
// (UserAchievementStored_t)、成就枚举与图标句柄。
// 签名对照 SDK v1.65 isteamuserstats.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <cstring>
#include <map>
#include <string>
#include <vector>

namespace steam_repro {

// UserAchievementStored_t 回调结构字段对照 isteamuserstats.h
// (m_nGameID / m_bGroupAchievement / m_rgchAchievementName /
//   m_nCurProgress / m_nMaxProgress)
struct MockUserAchievementStored {
  uint64_t gameId = 0;
  bool groupAchievement = false;
  std::string achievementName;
  uint32_t curProgress = 0;
  uint32_t maxProgress = 0;
};

class MockSteamUserStats {
 public:
  struct AchievementRec {
    bool achieved = false;
    uint32_t unlockTime = 0;
    bool hidden = false;
    std::string displayName;
    uint32_t curProgress = 0;
    uint32_t maxProgress = 0;
  };

  MockSteamUserStats() {
    register_("kill_100", "击杀100", false);
    register_("speedrun_under_1h", "一小时速通", true);
    register_("explorer", "探险家", false);
  }

  // isteamuserstats.h:SetAchievement:解锁成就
  bool setAchievement(const char* pchName) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    if (!it->second.achieved) {
      it->second.achieved = true;
      it->second.unlockTime = ++nowSeq_;
      newlyUnlocked_.push_back(pchName);
    }
    return true;
  }

  // isteamuserstats.h:GetAchievement:查询解锁状态
  bool getAchievement(const char* pchName, bool* pbAchieved) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    *pbAchieved = it->second.achieved;
    return true;
  }

  // isteamuserstats.h:GetAchievementAndUnlockTime:解锁状态 + 解锁时间
  bool getAchievementAndUnlockTime(const char* pchName, bool* pbAchieved,
                                   uint32_t* punUnlockTime) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    *pbAchieved = it->second.achieved;
    *punUnlockTime = it->second.unlockTime;
    return true;
  }

  // isteamuserstats.h:ClearAchievement:清除解锁状态
  bool clearAchievement(const char* pchName) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    it->second.achieved = false;
    it->second.unlockTime = 0;
    return true;
  }

  // isteamuserstats.h:IndicateAchievementProgress:仅记录进度,不自动解锁
  bool indicateAchievementProgress(const char* pchName, uint32_t nCurProgress,
                                   uint32_t nMaxProgress) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    it->second.curProgress = nCurProgress;
    it->second.maxProgress = nMaxProgress;
    return true;
  }

  // isteamuserstats.h:GetAchievementDisplayAttribute:接受 "name"/"desc"/"hidden"
  const char* getAchievementDisplayAttribute(const char* pchName, const char* pchKey) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return "";
    if (std::strcmp(pchKey, "hidden") == 0) return it->second.hidden ? "1" : "0";
    if (std::strcmp(pchKey, "name") == 0) return it->second.displayName.c_str();
    return "";
  }

  // isteamuserstats.h:GetAchievementIcon:图标句柄(0 表示未设置)
  int getAchievementIcon(const char* pchName) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return 0;
    return it->second.achieved ? 1 : 0;
  }

  // isteamuserstats.h:StoreStats:持久化。头文件注释明确
  // "will get a callback when set. And one callback for every new achievement",
  // 新成就事件即 UserAchievementStored_t。
  bool storeStats() {
    lastStoredEvent_ = MockUserAchievementStored{};
    if (!newlyUnlocked_.empty()) {
      const std::string& name = newlyUnlocked_.front();
      newlyUnlocked_.clear();
      lastStoredEvent_.achievementName = name;
      lastStoredEvent_.curProgress = achievements_[name].curProgress;
      lastStoredEvent_.maxProgress = achievements_[name].maxProgress;
    }
    return true;
  }

  // isteamuserstats.h:GetNumAchievements / GetAchievementName:成就枚举
  uint32_t getNumAchievements() const { return static_cast<uint32_t>(achievements_.size()); }
  const char* getAchievementName(uint32_t iAchievement) const {
    if (iAchievement >= achievements_.size()) return nullptr;
    auto it = achievements_.begin();
    for (uint32_t k = 0; k < iAchievement; ++k) ++it;
    return it->first.c_str();
  }

  const MockUserAchievementStored& lastStoredEvent() const { return lastStoredEvent_; }
  bool hasStoredEvent() const { return !lastStoredEvent_.achievementName.empty(); }

  uint32_t progress(const char* pchName) const {
    auto it = achievements_.find(pchName);
    return it == achievements_.end() ? 0 : it->second.curProgress;
  }

 private:
  void register_(const char* name, const char* display, bool hidden) {
    AchievementRec rec;
    rec.hidden = hidden;
    rec.displayName = display;
    achievements_[name] = rec;
  }

  uint32_t nowSeq_ = 0;
  std::map<std::string, AchievementRec> achievements_;
  std::vector<std::string> newlyUnlocked_;
  MockUserAchievementStored lastStoredEvent_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamUserStats stats;
  bool achieved = false;

  // 1. 初始未解锁:GetAchievement 返回 true(API 成功),pbAchieved 为 false
  CHECK(stats.getAchievement("kill_100", &achieved));
  CHECK(!achieved);

  // 2. SetAchievement 解锁成功
  CHECK(stats.setAchievement("kill_100"));

  // 3. GetAchievement 读回 true
  CHECK(stats.getAchievement("kill_100", &achieved));
  CHECK(achieved);

  // 4. GetAchievementAndUnlockTime:解锁时间非零
  uint32_t t = 0;
  CHECK(stats.getAchievementAndUnlockTime("kill_100", &achieved, &t));
  CHECK(achieved);
  CHECK(t > 0);

  // 5. 未注册的成就名返回 false
  CHECK(!stats.getAchievement("nonexistent", &achieved));

  // 6. ClearAchievement 复位
  CHECK(stats.clearAchievement("kill_100"));
  CHECK(stats.getAchievement("kill_100", &achieved));
  CHECK(!achieved);

  // 7. 隐藏成就属性与显示名
  CHECK(std::strcmp(stats.getAchievementDisplayAttribute("speedrun_under_1h", "hidden"), "1") == 0);
  CHECK(std::strcmp(stats.getAchievementDisplayAttribute("kill_100", "hidden"), "0") == 0);
  CHECK(std::strcmp(stats.getAchievementDisplayAttribute("kill_100", "name"), "击杀100") == 0);

  // 8. IndicateAchievementProgress 只记进度,不自动解锁
  CHECK(stats.indicateAchievementProgress("kill_100", 50, 100));
  CHECK(stats.progress("kill_100") == 50);
  CHECK(stats.getAchievement("kill_100", &achieved));
  CHECK(!achieved);

  // 9. 满进度仍需显式 SetAchievement;StoreStats 时产生新成就回调
  CHECK(stats.indicateAchievementProgress("kill_100", 100, 100));
  CHECK(stats.setAchievement("kill_100"));
  CHECK(stats.storeStats());
  CHECK(stats.hasStoredEvent());
  CHECK(stats.lastStoredEvent().achievementName == "kill_100");
  CHECK(stats.lastStoredEvent().curProgress == 100);

  // 10. 重复解锁幂等:不再产生新成就回调
  CHECK(stats.setAchievement("kill_100"));
  CHECK(stats.storeStats());
  CHECK(!stats.hasStoredEvent());

  // 11. 成就枚举:数量与名字
  CHECK(stats.getNumAchievements() == 3);
  CHECK(stats.getAchievementName(0) != nullptr);

  // 12. 图标句柄:已解锁有 handle,未解锁为 0
  CHECK(stats.getAchievementIcon("kill_100") == 1);
  CHECK(stats.getAchievementIcon("speedrun_under_1h") == 0);

  return lab::report("03-1 成就机制");
}

本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 32/32 通过。

小结

  • 成就接口:SetAchievement 解锁 → GetAchievement/GetAchievementAndUnlockTime 查询 → StoreStats 持久化。
  • 新成就事件:StoreStats 后每个新成就产生一个 UserAchievementStored_t 回调。
  • 判定在游戏、持久化在平台:IndicateAchievementProgress 只展示进度,解锁由游戏代码决定。
  • 元数据与枚举:隐藏属性、图标句柄、成就清单枚举都走 isteamuserstats.h。

阅读导航:上一节:2.3 加密票据与身份边界 · 下一节:3.2 统计机制 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图