《Steam 游戏平台:开发与商业化》3.3 成就与统计的策略

成就与统计的接入不只是调接口,还要做策略:用统计驱动的数据规则触发解锁、用全局解锁率反馈难度与迭代、用隐藏成就管理探索节奏。本节讲这三类策略的工程落法,lab 用 C++ 模拟数据驱动解锁、百分比反馈与隐藏成就可见性。

3.3 成就与统计的策略

3.1/3.2 讲清了成就与统计的接口,这一节回答工程策略问题:解锁规则放哪、难度怎么校准、隐藏成就怎么管理。SDK 只提供机制(SetAchievement 解锁、GetAchievementAchievedPercent 查解锁率),判定与节奏由游戏代码决定。

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

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

  • Steam 发行专题 (操作手册)讲「后台配置成就触发方式」;本节讲「代码里落地数据驱动解锁规则的工程语义」。
  • 卷一讲成就难度曲线如何影响留存;本节讲解锁率数据怎么读回来校准难度。
  • lab 用纯 C++ 模拟规则引擎与全局百分比反馈,不依赖 Steam 客户端运行。

数据驱动的解锁规则

SDK 不会自动解锁成就——规则必须由游戏实现。最常见的落法是把「统计 → 成就」映射成一张数据表:

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

工程语义:

  1. 规则层在游戏内、在 SetAchievement 之前:统计更新时先查表(如 kills_total ≥ 100 → first_kill),达标才调 SetAchievement。
  2. 规则应幂等:同一成就只解锁一次;重复达标不能重复解锁、重复触发回调(3.1 的 UserAchievementStored_t)。
  3. 无门槛成就(如「开局即得」)与门槛成就要分开建模:门槛成就绑定一个统计名 + 阈值,规则引擎只在对应统计更新时检查。

难度反馈:全局解锁率

成就做没做难,看全局解锁率:

// isteamuserstats.h:RequestGlobalAchievementPercentages / GetAchievementAchievedPercent(SDK v1.65 头文件摘录,已删减)
virtual SteamAPICall_t RequestGlobalAchievementPercentages() = 0;
virtual bool GetAchievementAchievedPercent( const char *pchName, float *pflPercent ) = 0;
// isteamuserstats.h:GetMostAchievedAchievementInfo / GetNextMostAchievedAchievementInfo(SDK v1.65 头文件摘录,已删减)
virtual int GetMostAchievedAchievementInfo( char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved ) = 0;
virtual int GetNextMostAchievedAchievementInfo( int iIteratorPrevious, char *pchName, uint32 unNameBufLen, float *pflPercent, bool *pbAchieved ) = 0;

工程语义:

  1. 百分比是异步数据:先 RequestGlobalAchievementPercentages() 发起,完成后(GlobalAchievementPercentagesReady_t 回调)GetAchievementAchievedPercent 才可用;请求前调用返回 false。
  2. 迭代器风格:GetMostAchievedAchievementInfo 返回「最热门成就」的索引,之后连续调 GetNextMostAchievedAchievementInfo(上一次索引) 按解锁率降序遍历,末尾返回 -1。
  3. 用解锁率校准难度:解锁率过低(本 lab 以 <1% 为「过难」的模型假设阈值,非官方数值)的成就要么降门槛、要么调整节奏。

隐藏成就与可见性

// isteamuserstats.h:GetAchievementDisplayAttribute(SDK v1.65 头文件摘录,已删减)
// Get general attributes for an achievement. Accepts the following keys:
// - "name" and "desc" for retrieving the localized achievement name and description (returned in UTF8)
virtual bool GetAchievementDisplayAttribute( const char *pchName, const char *pchKey ) = 0;

工程语义:

  1. 隐藏成就是产品节奏工具:hidden 属性为 "1" 时,解锁前不向玩家展示;适合彩蛋、剧透敏感、长线目标。
  2. 解锁后应进入可见列表:隐藏只是展示层遮蔽,解锁逻辑与普通成就一致。
  3. 进度提示不破坏隐藏:IndicateAchievementProgress 仍可驱动进度展示,但不应泄露未解锁隐藏成就的存在(UI 层面控制)。

接口签名对照

头文件条目语义
isteamuserstats.hSetAchievement规则落地通道
isteamuserstats.hRequestGlobalAchievementPercentages异步就绪解锁率表
isteamuserstats.hGetAchievementAchievedPercent单成就解锁率
isteamuserstats.hGetMostAchievedAchievementInfo/GetNextMostAchievedAchievementInfo按热度迭代
isteamuserstats.hGetAchievementDisplayAttribute隐藏属性
isteamuserstats.hIndicateAchievementProgress进度提示

数据口径与来源

  • 接口签名与语义:SDK v1.65 public/steam/isteamuserstats.h 可实证。
  • 「请求前 GetAchievementAchievedPercent 不可用」「迭代到末尾返回 -1」:头文件注释明文。
  • 全局解锁率的具体数值、隐藏成就策略:partner 文档登录后可见 / 运营口径,以官方当前为准;「<1% 视为过难」是本 lab 的模型假设阈值,非官方数值。

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

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

下面的仿真复现「成就与统计的策略」的工程语义:数据驱动解锁规则(统计达标触发 SetAchievement)、全局解锁率百分比反馈与按热度迭代、隐藏成就可见性管理、难易度反馈与进度提示。它与 src/03-3-achievement-stats-strategy.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/03-3-achievement-stats-strategy.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/03-3-achievement-stats-strategy.cpp -o bin/03-3-achievement-stats-strategy && ./bin/03-3-achievement-stats-strategy
//
// mock:复现「成就与统计的策略」的工程语义——数据驱动解锁规则
// (统计达标触发 SetAchievement)、全局成就百分比反馈
// (RequestGlobalAchievementPercentages/GetAchievementAchievedPercent/
//  GetMostAchievedAchievementInfo)、隐藏成就的可见性管理、
// 难易度反馈与进度提示。签名对照 SDK v1.65 isteamuserstats.h,非 Valve 实现。
#include "verify.h"

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

namespace steam_repro {

class MockAchievementEngine {
 public:
  struct AchievementDef {
    std::string displayName;
    bool hidden = false;
    std::string thresholdStat;   // 空表示无统计门槛
    uint32_t threshold = 0;
    float achievedPercent = 0.0f;
  };

  MockAchievementEngine() {
    defs_["starter"] = {"起步", false, "", 0, 62.0f};
    defs_["explorer"] = {"探险家", false, "", 0, 18.0f};
    defs_["first_kill"] = {"首杀", false, "kills_total", 100, 55.0f};
    defs_["perfectionist"] = {"完美主义者", false, "perfect_scores", 10, 0.8f};
    defs_["secret"] = {"秘密成就", true, "", 0, 3.0f};
  }

  // 游戏侧数据驱动规则层:统计更新后检查门槛,达标即调用 SetAchievement。
  // SDK 本身不会自动解锁,这里模拟的是「游戏用 SetAchievement 落地规则」。
  bool applyStatUpdate(const char* statName, uint32_t value) {
    stats_[statName] = value;
    for (auto& kv : defs_) {
      const AchievementDef& def = kv.second;
      if (!def.thresholdStat.empty() && def.thresholdStat == statName &&
          value >= def.threshold && !unlocked_[kv.first]) {
        setAchievement(kv.first.c_str());
      }
    }
    return true;
  }

  // isteamuserstats.h:SetAchievement
  bool setAchievement(const char* pchName) {
    auto it = defs_.find(pchName);
    if (it == defs_.end()) return false;
    if (!unlocked_[pchName]) {
      unlocked_[pchName] = true;
      unlockTimeline_.push_back(pchName);
    }
    return true;
  }

  // isteamuserstats.h:GetAchievement
  bool getAchievement(const char* pchName, bool* pbAchieved) {
    auto it = defs_.find(pchName);
    if (it == defs_.end()) return false;
    *pbAchieved = unlocked_[pchName];
    return true;
  }

  // isteamuserstats.h:RequestGlobalAchievementPercentages:异步就绪百分比表
  bool requestGlobalAchievementPercentages() {
    globalReady_ = true;
    sorted_.clear();
    for (auto& kv : defs_) sorted_.push_back(kv.first);
    std::sort(sorted_.begin(), sorted_.end(),
              [this](const std::string& a, const std::string& b) {
                return defs_[a].achievedPercent > defs_[b].achievedPercent;
              });
    return true;
  }

  // isteamuserstats.h:GetAchievementAchievedPercent:请求前不可用
  bool getAchievementAchievedPercent(const char* pchName, float* pflPercent) {
    if (!globalReady_) return false;
    auto it = defs_.find(pchName);
    if (it == defs_.end()) return false;
    *pflPercent = it->second.achievedPercent;
    return true;
  }

  // isteamuserstats.h:GetMostAchievedAchievementInfo:返回迭代器索引
  int getMostAchievedAchievementInfo(char* pchName, uint32_t unNameBufLen,
                                     float* pflPercent, bool* pbAchieved) {
    if (!globalReady_ || sorted_.empty()) return -1;
    return fill_(0, pchName, unNameBufLen, pflPercent, pbAchieved);
  }

  // isteamuserstats.h:GetNextMostAchievedAchievementInfo
  int getNextMostAchievedAchievementInfo(int iIteratorPrevious, char* pchName,
                                         uint32_t unNameBufLen,
                                         float* pflPercent, bool* pbAchieved) {
    if (!globalReady_ || iIteratorPrevious < 0) return -1;
    int next = iIteratorPrevious + 1;
    if (next >= static_cast<int>(sorted_.size())) return -1;
    return fill_(next, pchName, unNameBufLen, pflPercent, pbAchieved);
  }

  // isteamuserstats.h:GetAchievementDisplayAttribute:隐藏属性
  const char* getAchievementDisplayAttribute(const char* pchName, const char* pchKey) {
    auto it = defs_.find(pchName);
    if (it == defs_.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 "";
  }

  // 可见成就列表:隐藏成就在解锁后才进入列表
  std::vector<std::string> visibleAchievements() const {
    std::vector<std::string> out;
    for (auto& kv : defs_) {
      bool hidden = kv.second.hidden;
      bool isUnlocked = unlocked_.find(kv.first) != unlocked_.end() && unlocked_.at(kv.first);
      if (!hidden || isUnlocked) out.push_back(kv.first);
    }
    return out;
  }

  // 难易度反馈:全局解锁率 < 1% 视为「过难」(模型假设的运营阈值)
  bool isHardAchievement(const char* pchName) const {
    auto it = defs_.find(pchName);
    if (it == defs_.end()) return false;
    return it->second.achievedPercent < 1.0f;
  }

  // isteamuserstats.h:IndicateAchievementProgress:进度提示(展示用)
  bool indicateAchievementProgress(const char* pchName, uint32_t nCurProgress,
                                   uint32_t nMaxProgress) {
    auto it = defs_.find(pchName);
    if (it == defs_.end()) return false;
    progressCur_[pchName] = nCurProgress;
    progressMax_[pchName] = nMaxProgress;
    return true;
  }

  uint32_t progressCur(const char* pchName) const {
    auto it = progressCur_.find(pchName);
    return it == progressCur_.end() ? 0 : it->second;
  }
  uint32_t progressMax(const char* pchName) const {
    auto it = progressMax_.find(pchName);
    return it == progressMax_.end() ? 0 : it->second;
  }

  const std::vector<std::string>& unlockTimeline() const { return unlockTimeline_; }

 private:
  int fill_(int idx, char* pchName, uint32_t unNameBufLen, float* pflPercent,
            bool* pbAchieved) {
    const std::string& name = sorted_[idx];
    const AchievementDef& def = defs_[name];
    if (unNameBufLen > 0) {
      std::strncpy(pchName, name.c_str(), unNameBufLen);
      pchName[unNameBufLen - 1] = '\0';
    }
    *pflPercent = def.achievedPercent;
    *pbAchieved = unlocked_[name];
    return idx;
  }

  std::map<std::string, AchievementDef> defs_;
  std::map<std::string, bool> unlocked_;
  std::map<std::string, uint32_t> stats_;
  std::map<std::string, uint32_t> progressCur_;
  std::map<std::string, uint32_t> progressMax_;
  std::vector<std::string> unlockTimeline_;
  std::vector<std::string> sorted_;
  bool globalReady_ = false;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockAchievementEngine engine;
  bool ach = false;

  // 1. 统计未达标:成就仍锁定
  CHECK(engine.applyStatUpdate("kills_total", 99));
  CHECK(engine.getAchievement("first_kill", &ach));
  CHECK(!ach);

  // 2. 统计达标:数据驱动规则触发解锁
  CHECK(engine.applyStatUpdate("kills_total", 100));
  CHECK(engine.getAchievement("first_kill", &ach));
  CHECK(ach);

  // 3. 解锁时间线记录
  CHECK(engine.unlockTimeline().size() == 1);
  CHECK(engine.unlockTimeline()[0] == "first_kill");

  // 4. 规则幂等:重复达标不重复解锁
  CHECK(engine.applyStatUpdate("kills_total", 200));
  CHECK(engine.unlockTimeline().size() == 1);

  // 5. 百分比请求前不可用
  float pct = 0.0f;
  CHECK(!engine.getAchievementAchievedPercent("starter", &pct));

  // 6. 请求后读取全局解锁率
  CHECK(engine.requestGlobalAchievementPercentages());
  CHECK(engine.getAchievementAchievedPercent("starter", &pct));
  CHECK(std::fabs(pct - 62.0f) < 1e-6);
  CHECK(engine.getAchievementAchievedPercent("perfectionist", &pct));
  CHECK(std::fabs(pct - 0.8f) < 1e-6);

  // 7. 难易度反馈:<1% 视为过难(模型假设阈值)
  CHECK(engine.isHardAchievement("perfectionist"));
  CHECK(!engine.isHardAchievement("starter"));

  // 8. 最热门成就迭代:starter(62%)居首
  char nameBuf[64] = {0};
  CHECK(engine.getMostAchievedAchievementInfo(nameBuf, sizeof(nameBuf), &pct, &ach) == 0);
  CHECK(std::strcmp(nameBuf, "starter") == 0);

  // 9. 依次迭代到次热门与最稀有
  CHECK(engine.getNextMostAchievedAchievementInfo(0, nameBuf, sizeof(nameBuf), &pct, &ach) == 1);
  CHECK(std::strcmp(nameBuf, "first_kill") == 0);
  CHECK(engine.getNextMostAchievedAchievementInfo(1, nameBuf, sizeof(nameBuf), &pct, &ach) == 2);
  CHECK(std::strcmp(nameBuf, "explorer") == 0);

  // 10. 迭代到末尾返回 -1
  CHECK(engine.getNextMostAchievedAchievementInfo(4, nameBuf, sizeof(nameBuf), &pct, &ach) == -1);

  // 11. 隐藏成就:未解锁时不在可见列表,属性标记 "1"
  std::vector<std::string> visible = engine.visibleAchievements();
  CHECK(std::find(visible.begin(), visible.end(), "secret") == visible.end());
  CHECK(std::strcmp(engine.getAchievementDisplayAttribute("secret", "hidden"), "1") == 0);

  // 12. 解锁后隐藏成就进入可见列表
  CHECK(engine.setAchievement("secret"));
  visible = engine.visibleAchievements();
  CHECK(std::find(visible.begin(), visible.end(), "secret") != visible.end());

  // 13. 进度提示只做展示,不改变解锁状态
  CHECK(engine.indicateAchievementProgress("first_kill", 80, 100));
  CHECK(engine.progressCur("first_kill") == 80);
  CHECK(engine.progressMax("first_kill") == 100);

  return lab::report("03-3 成就与统计的策略");
}

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

小结

  • 规则在游戏侧:统计达标 → SetAchievement,幂等落地。
  • 难度用全局解锁率校准:RequestGlobalAchievementPercentages → GetAchievementAchievedPercent/迭代器。
  • 隐藏成就是节奏工具:解锁前遮蔽,解锁后可见,进度提示不泄露。
  • 数值标注:解锁率阈值属模型假设,以官方为准。

阅读导航:上一节:3.2 统计机制 · 下一节:4.1 云存储机制 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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