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;
工程语义:
- 类型是重载的:同一名字的 int32/float 由调用哪个重载决定;未在后台登记、或类型不匹配的统计,
SetStat/GetStat返回 false。 - 读取是「输出参数」:
GetStat返回 bool 表示成功与否,数值写入*pData;本 lab 约定已登记但未写入的统计读回 0。 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
工程语义:
StoreStats是约束闸门:后台登记的统计有上限(如kills上限 1000);越界值上传会被服务器拒绝。k_EResultInvalidParam= 8 表示拒绝:头文件注释明文——一个或多个统计被拒,服务器会回推修正后的值,游戏应重新迭代统计以保持同步。- 拒绝不是灾难:客户端应把本地越界值收敛到服务器上限,下次
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;
工程语义:
ResetAllStats(bAchievementsToo):把统计归零;参数决定是否连成就一起清。重置后已登记的统计名仍可读(读回 0)。RequestGlobalStats(nHistoryDays)拉全局聚合:仅对后台标记为 aggregated 的统计有效;异步,结果在GlobalStatsReceived_t中;nHistoryDays历史天数上限 60(头文件注释明文)。GetGlobalStat在请求就绪前不可用:先RequestGlobalStats成功,再读 int64/double 两个重载的聚合值。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamuserstats.h | ISteamUserStats::GetStat/SetStat | int32/float 写读 |
isteamuserstats.h | UpdateAvgRateStat | 会话累加平均速率 |
isteamuserstats.h | StoreStats | 持久化 + 约束校验 |
steamclientpublic.h | k_EResultInvalidParam | 服务器拒绝(=8) |
isteamuserstats.h | ResetAllStats | 统计/成就归零 |
isteamuserstats.h | RequestGlobalStats/GetGlobalStat | 全局聚合统计 |
数据口径与来源
- 接口签名与重载(
GetStat/SetStat/GetGlobalStat的 int64/double):SDK v1.65public/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 成就与统计的策略 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。