《Steam 游戏平台:开发与商业化》3.2 统计机制

统计机制是与成就并列的数值持久化通道:SetStat/GetStat 写读 int32 与 float、UpdateAvgRateStat 累加平均、StoreStats 做约束校验并处理 k_EResultInvalidParam 的服务器回推、RequestGlobalStats/GetGlobalStat 读全局聚合。本节讲统计接口的工程语义,lab 用 C++ 模拟写入、校验、重置与全局聚合。

3.2 统计机制

统计(Stats)与成就在工程上是同一套「数值持久化」体系:成就记录布尔里程碑,统计记录连续数值(击杀数、胜场、命中率)。接入要回答的问题:数值怎么登记、怎么校验、服务器拒绝后怎么办、聚合口径从哪来。

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

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

  • Steam 发行专题 (操作手册)讲「后台把统计标记为 aggregated 等属性」;本节讲「代码里写读统计的接口语义」。
  • 卷一讲统计如何支撑长期留存;本节讲统计的工程生命周期——登记、写读、校验、重置、全局聚合。
  • lab 用纯 C++ 模拟统计约束与服务器回推,不依赖 Steam 客户端运行。

写读与登记

统计必须先在后台登记(名字 + 类型 + 上限),代码侧才有对应的访问器:

// isteamuserstats.h:GetStat / SetStat(SDK v1.65 头文件摘录,已删减)
virtual bool GetStat( const char *pchName, int32 *pData ) = 0;
virtual bool GetStat( const char *pchName, float *pData ) = 0;
virtual bool SetStat( const char *pchName, int32 nData ) = 0;
virtual bool SetStat( const char *pchName, float fData ) = 0;

工程语义:

  1. 类型是重载的:同一名字的 int32/float 由调用哪个重载决定;未在后台登记、或类型不匹配的统计,SetStat/GetStat 返回 false。
  2. 读取是「输出参数」:GetStat 返回 bool 表示成功与否,数值写入 *pData;本 lab 约定已登记但未写入的统计读回 0。
  3. SetStat 只改内存态:数值要等 StoreStats 才推上服务器(与成就一致)。

平均速率与累加

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

工程语义:

  • 适合速率型统计(每分钟击杀等):每次会话结束把「本次计数」与「本次时长」累加进服务器侧的平均值。
  • 参数是会话增量而非当前值:flCountThisSession 是本会话新增的量,dSessionLength 是本会话时长(秒)。多次调用后 avg = Σcount / Σtime。

持久化、校验与回推

// isteamuserstats.h:StoreStats(SDK v1.65 头文件摘录,已删减)
// If the callback has a result of k_EResultInvalidParam, one or more stats
// uploaded has been rejected, either because they broke constraints
// or were out of date. In this case the server sends back updated values.
// The stats should be re-iterated to keep in sync.
virtual bool StoreStats() = 0;
// steamclientpublic.h:k_EResultInvalidParam(SDK v1.65 头文件摘录,已删减)
k_EResultInvalidParam = 8,					// a parameter is incorrect

工程语义:

  1. StoreStats 是约束闸门:后台登记的统计有上限(如 kills 上限 1000);越界值上传会被服务器拒绝。
  2. k_EResultInvalidParam = 8 表示拒绝:头文件注释明文——一个或多个统计被拒,服务器会回推修正后的值,游戏应重新迭代统计以保持同步。
  3. 拒绝不是灾难:客户端应把本地越界值收敛到服务器上限,下次 StoreStats 恢复正常(本 lab 模拟这一修正)。

重置与全局聚合

// isteamuserstats.h:ResetAllStats / RequestGlobalStats / GetGlobalStat(SDK v1.65 头文件摘录,已删减)
virtual bool ResetAllStats( bool bAchievementsToo ) = 0;
virtual SteamAPICall_t RequestGlobalStats( int nHistoryDays ) = 0;
virtual bool GetGlobalStat( const char *pchStatName, int64 *pData ) = 0;
virtual bool GetGlobalStat( const char *pchStatName, double *pData ) = 0;

工程语义:

  1. ResetAllStats(bAchievementsToo):把统计归零;参数决定是否连成就一起清。重置后已登记的统计名仍可读(读回 0)。
  2. RequestGlobalStats(nHistoryDays) 拉全局聚合:仅对后台标记为 aggregated 的统计有效;异步,结果在 GlobalStatsReceived_t 中;nHistoryDays 历史天数上限 60(头文件注释明文)。
  3. GetGlobalStat 在请求就绪前不可用:先 RequestGlobalStats 成功,再读 int64/double 两个重载的聚合值。

接口签名对照

头文件条目语义
isteamuserstats.hISteamUserStats::GetStat/SetStatint32/float 写读
isteamuserstats.hUpdateAvgRateStat会话累加平均速率
isteamuserstats.hStoreStats持久化 + 约束校验
steamclientpublic.hk_EResultInvalidParam服务器拒绝(=8)
isteamuserstats.hResetAllStats统计/成就归零
isteamuserstats.hRequestGlobalStats/GetGlobalStat全局聚合统计

数据口径与来源

  • 接口签名与重载(GetStat/SetStat/GetGlobalStat 的 int64/double):SDK v1.65 public/steam/isteamuserstats.h 可实证。
  • k_EResultInvalidParam = 8:steamclientpublic.h 可实证。
  • 「StoreStats 拒绝后服务器回推修正值」「RequestGlobalStats 的 nHistoryDays 上限 60」:isteamuserstats.h 注释明文。
  • 后台对统计标记 aggregated、上限配置:partner.steamgames.com 登录后文档,以官方当前为准。

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

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

下面的仿真复现「统计机制」的工程语义:int32/float 写读、UpdateAvgRateStat 累加平均、StoreStats 约束校验与 k_EResultInvalidParam 回推修正、ResetAllStats 归零、RequestGlobalStats/GetGlobalStat 全局聚合。它与 src/03-2-stats-mechanics.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/03-2-stats-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/03-2-stats-mechanics.cpp -o bin/03-2-stats-mechanics && ./bin/03-2-stats-mechanics
//
// mock:复现统计机制的工程语义——GetStat/SetStat(int32 与 float)、
// UpdateAvgRateStat 累加平均、StoreStats 的约束校验与
// k_EResultInvalidParam 处理(服务器回推修正值)、ResetAllStats、
// RequestGlobalStats/GetGlobalStat 全局聚合统计。
// 签名对照 SDK v1.65 isteamuserstats.h / steamclientpublic.h,非 Valve 实现。
#include "verify.h"

#include <cmath>
#include <cstdint>
#include <map>
#include <string>

namespace steam_repro {

// k_EResultOK / k_EResultInvalidParam 对照 steamclientpublic.h EResult
static constexpr int kEResultOK = 1;
static constexpr int kEResultInvalidParam = 8;

class MockSteamUserStats {
 public:
  struct AvgRec {
    double totalCount = 0.0;
    double totalTime = 0.0;
    float avg = 0.0f;
  };

  MockSteamUserStats() {
    intMax_["kills"] = 1000;
    intMax_["wins"] = 10000;
    achievements_["champion"] = false;
    achievements_["veteran"] = false;
  }

  // isteamuserstats.h:SetStat(int32 重载):未注册的统计名返回 false
  bool setStat(const char* pchName, int32_t nData) {
    if (intMax_.find(pchName) == intMax_.end()) return false;
    intStats_[pchName] = nData;
    return true;
  }

  // isteamuserstats.h:SetStat(float 重载)
  bool setStat(const char* pchName, float fData) {
    if (!isFloatStat_(pchName)) return false;
    floatStats_[pchName] = fData;
    return true;
  }

  // isteamuserstats.h:GetStat(int32 重载):已注册但尚未写入的统计返回 0
  bool getStat(const char* pchName, int32_t* pData) {
    auto it = intStats_.find(pchName);
    if (it == intStats_.end()) {
      if (intMax_.find(pchName) == intMax_.end()) return false;
      *pData = 0;
      return true;
    }
    *pData = it->second;
    return true;
  }

  // isteamuserstats.h:GetStat(float 重载)
  bool getStat(const char* pchName, float* pData) {
    auto it = floatStats_.find(pchName);
    if (it == floatStats_.end()) return false;
    *pData = it->second;
    return true;
  }

  // isteamuserstats.h:UpdateAvgRateStat:会话内累加平均速率
  bool updateAvgRateStat(const char* pchName, float flCountThisSession,
                         double dSessionLength) {
    if (!isFloatStat_(pchName)) return false;
    AvgRec& rec = avg_[pchName];
    rec.totalCount += flCountThisSession;
    rec.totalTime += dSessionLength;
    rec.avg = static_cast<float>(rec.totalCount / rec.totalTime);
    floatStats_[pchName] = rec.avg;
    return true;
  }

  float avgRate(const char* pchName) const {
    auto it = avg_.find(pchName);
    return it == avg_.end() ? 0.0f : it->second.avg;
  }

  // isteamuserstats.h:StoreStats:约束校验。头文件注释——
  // "If the callback has a result of k_EResultInvalidParam, one or more stats
  //  uploaded has been rejected... In this case the server sends back updated
  //  values." mock 在拒绝时把越界统计修正为服务器侧上限。
  bool storeStats() {
    invalidParam_ = false;
    for (auto& kv : intStats_) {
      auto limit = intMax_.find(kv.first);
      if (limit != intMax_.end() && kv.second > limit->second) {
        kv.second = limit->second;  // 服务器回推修正值
        invalidParam_ = true;
      }
    }
    lastStoreResult_ = invalidParam_ ? kEResultInvalidParam : kEResultOK;
    return !invalidParam_;
  }

  int lastStoreResult() const { return lastStoreResult_; }
  bool lastStoreInvalidParam() const { return invalidParam_; }

  // isteamuserstats.h:ResetAllStats:统计归零(已注册统计仍可读),
  // bAchievementsToo 决定是否连成就一起清
  bool resetAllStats(bool bAchievementsToo) {
    for (const auto& kv : intMax_) intStats_[kv.first] = 0;
    floatStats_.clear();
    avg_.clear();
    if (bAchievementsToo) {
      for (auto& kv : achievements_) kv.second = false;
    }
    return true;
  }

  bool setAchievement(const char* pchName) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    it->second = true;
    return true;
  }

  bool getAchievement(const char* pchName, bool* pbAchieved) {
    auto it = achievements_.find(pchName);
    if (it == achievements_.end()) return false;
    *pbAchieved = it->second;
    return true;
  }

  // isteamuserstats.h:RequestGlobalStats:异步请求全局聚合统计;
  // nHistoryDays 上限 60(头文件注释明文),mock 同步就绪数据。
  uint64_t requestGlobalStats(int nHistoryDays) {
    if (nHistoryDays > 60) nHistoryDays = 60;
    lastHistoryDays_ = nHistoryDays;
    globalReady_ = true;
    globalInt_["total_games"] = 1234567;
    globalDouble_["total_hours"] = 9876543.5;
    return ++nextCall_;
  }

  // isteamuserstats.h:GetGlobalStat(int64 重载):请求前不可用
  bool getGlobalStat(const char* pchStatName, int64_t* pData) {
    if (!globalReady_) return false;
    auto it = globalInt_.find(pchStatName);
    if (it == globalInt_.end()) return false;
    *pData = it->second;
    return true;
  }

  // isteamuserstats.h:GetGlobalStat(double 重载)
  bool getGlobalStat(const char* pchStatName, double* pData) {
    if (!globalReady_) return false;
    auto it = globalDouble_.find(pchStatName);
    if (it == globalDouble_.end()) return false;
    *pData = it->second;
    return true;
  }

  int lastHistoryDays() const { return lastHistoryDays_; }

 private:
  bool isFloatStat_(const char* pchName) const {
    return std::string(pchName) == "accuracy" || std::string(pchName) == "kills_per_min";
  }

  std::map<std::string, int32_t> intStats_;
  std::map<std::string, int32_t> intMax_;
  std::map<std::string, float> floatStats_;
  std::map<std::string, AvgRec> avg_;
  std::map<std::string, bool> achievements_;
  bool invalidParam_ = false;
  int lastStoreResult_ = kEResultOK;
  bool globalReady_ = false;
  int lastHistoryDays_ = 0;
  std::map<std::string, int64_t> globalInt_;
  std::map<std::string, double> globalDouble_;
  uint64_t nextCall_ = 0;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamUserStats s;
  int32_t iv = 0;
  float fv = 0.0f;

  // 1. 默认统计值为 0
  CHECK(s.getStat("kills", &iv));
  CHECK(iv == 0);

  // 2. SetStat(int32) 写入并读回
  CHECK(s.setStat("kills", 42));
  CHECK(s.getStat("kills", &iv));
  CHECK(iv == 42);

  // 3. SetStat(float) 写入并读回
  CHECK(s.setStat("accuracy", 0.85f));
  CHECK(s.getStat("accuracy", &fv));
  CHECK(std::fabs(fv - 0.85f) < 1e-6);

  // 4. 未注册统计名:读写均失败
  CHECK(!s.getStat("not_registered", &iv));
  CHECK(!s.setStat("not_registered", 5));

  // 5. UpdateAvgRateStat:两次会话累加平均 = (30+60)/(300+300)
  CHECK(s.updateAvgRateStat("kills_per_min", 30.0f, 300.0));
  CHECK(s.updateAvgRateStat("kills_per_min", 60.0f, 300.0));
  CHECK(std::fabs(s.avgRate("kills_per_min") - 0.15f) < 1e-6);

  // 6. StoreStats 通过:result == k_EResultOK
  CHECK(s.storeStats());
  CHECK(s.lastStoreResult() == kEResultOK);

  // 7. 越界统计被 StoreStats 拒绝:k_EResultInvalidParam
  CHECK(s.setStat("kills", 5000));  // 超过服务器上限 1000
  CHECK(!s.storeStats());
  CHECK(s.lastStoreResult() == kEResultInvalidParam);
  CHECK(s.lastStoreInvalidParam());

  // 8. 拒绝后服务器回推修正值
  CHECK(s.getStat("kills", &iv));
  CHECK(iv == 1000);

  // 9. ResetAllStats(false):统计清零,成就保留
  CHECK(s.setAchievement("champion"));
  CHECK(s.resetAllStats(false));
  CHECK(s.getStat("kills", &iv));
  CHECK(iv == 0);
  bool ach = false;
  CHECK(s.getAchievement("champion", &ach));
  CHECK(ach);

  // 10. ResetAllStats(true):成就一并清除
  CHECK(s.resetAllStats(true));
  CHECK(s.getAchievement("champion", &ach));
  CHECK(!ach);

  // 11. 全局统计在 RequestGlobalStats 之前不可用
  int64_t gv = 0;
  CHECK(!s.getGlobalStat("total_games", &gv));

  // 12. RequestGlobalStats 后 int64 与 double 全局统计可读
  CHECK(s.requestGlobalStats(60) != 0);
  CHECK(s.getGlobalStat("total_games", &gv));
  CHECK(gv == 1234567);
  double dv = 0.0;
  CHECK(s.getGlobalStat("total_hours", &dv));
  CHECK(std::fabs(dv - 9876543.5) < 1.0);

  // 13. nHistoryDays 超过 60 被收敛到 60
  CHECK(s.requestGlobalStats(120) != 0);
  CHECK(s.lastHistoryDays() == 60);

  return lab::report("03-2 统计机制");
}

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

小结

  • 统计写读:int32/float 重载,未登记返回 false;内存态由 StoreStats 落库。
  • 校验与回推:越界值被 k_EResultInvalidParam 拒绝,服务器回推修正值。
  • 重置:ResetAllStats 归零但保留登记名。
  • 全局聚合:先 RequestGlobalStats(上限 60 天)再 GetGlobalStat。

阅读导航:上一节:3.1 成就机制 · 下一节:3.3 成就与统计的策略 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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