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;
工程语义:
- 规则层在游戏内、在
SetAchievement之前:统计更新时先查表(如kills_total ≥ 100 → first_kill),达标才调SetAchievement。 - 规则应幂等:同一成就只解锁一次;重复达标不能重复解锁、重复触发回调(3.1 的
UserAchievementStored_t)。 - 无门槛成就(如「开局即得」)与门槛成就要分开建模:门槛成就绑定一个统计名 + 阈值,规则引擎只在对应统计更新时检查。
难度反馈:全局解锁率
成就做没做难,看全局解锁率:
// 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;
工程语义:
- 百分比是异步数据:先
RequestGlobalAchievementPercentages()发起,完成后(GlobalAchievementPercentagesReady_t回调)GetAchievementAchievedPercent才可用;请求前调用返回 false。 - 迭代器风格:
GetMostAchievedAchievementInfo返回「最热门成就」的索引,之后连续调GetNextMostAchievedAchievementInfo(上一次索引)按解锁率降序遍历,末尾返回 -1。 - 用解锁率校准难度:解锁率过低(本 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;
工程语义:
- 隐藏成就是产品节奏工具:
hidden属性为"1"时,解锁前不向玩家展示;适合彩蛋、剧透敏感、长线目标。 - 解锁后应进入可见列表:隐藏只是展示层遮蔽,解锁逻辑与普通成就一致。
- 进度提示不破坏隐藏:
IndicateAchievementProgress仍可驱动进度展示,但不应泄露未解锁隐藏成就的存在(UI 层面控制)。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamuserstats.h | SetAchievement | 规则落地通道 |
isteamuserstats.h | RequestGlobalAchievementPercentages | 异步就绪解锁率表 |
isteamuserstats.h | GetAchievementAchievedPercent | 单成就解锁率 |
isteamuserstats.h | GetMostAchievedAchievementInfo/GetNextMostAchievedAchievementInfo | 按热度迭代 |
isteamuserstats.h | GetAchievementDisplayAttribute | 隐藏属性 |
isteamuserstats.h | IndicateAchievementProgress | 进度提示 |
数据口径与来源
- 接口签名与语义: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 云存储机制 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。