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;
工程语义:
- 返回 bool 是「调用是否成功」,不是「是否已解锁」:
SetAchievement返回 false 通常表示成就在后台未配置或名字不合法;GetAchievement把结果写到pbAchieved输出参数。 GetAchievementAndUnlockTime附带解锁时间:头文件注释明确——时间为 0 表示该成就在 2009 年 12 月(Steam 开始记录解锁时间)之前解锁。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
};
工程语义:
StoreStats把当前全部统计与成就状态推上服务器,成功后收到回调;每解锁一个新成就,就有一个UserAchievementStored_t回调(头文件注释明文)。- 回调里的进度字段有特殊含义:
m_nCurProgress/m_nMaxProgress都为零,表示该成就已被完整解锁;非零表示进度型成就当前进度。 - 解锁必须先
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;
工程语义:
- 隐藏成就由显示属性控制:
GetAchievementDisplayAttribute接受"name"/"desc"/"hidden"等键,hidden返回"1"/"0";隐藏成就在解锁前不向玩家展示。 IndicateAchievementProgress只记进度、不自动解锁:它驱动覆盖层的「进度条」展示;解锁判定仍在游戏代码里(统计达标后由SetAchievement落地,见 3.3)。GetNumAchievements/GetAchievementName提供枚举:用于成就列表 UI;头文件注释提醒,一般游戏应把成就清单编译进客户端,不应运行时依赖枚举。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamuserstats.h | ISteamUserStats::SetAchievement | 解锁成就(内存态) |
isteamuserstats.h | GetAchievement/GetAchievementAndUnlockTime | 查询状态与解锁时间 |
isteamuserstats.h | ClearAchievement | 复位成就(测试用) |
isteamuserstats.h | StoreStats | 持久化到服务器,新成就触发回调 |
isteamuserstats.h | UserAchievementStored_t | 新成就存储回调结构 |
isteamuserstats.h | GetAchievementDisplayAttribute/GetAchievementIcon | 元数据与图标 |
isteamuserstats.h | IndicateAchievementProgress | 进度提示(不自动解锁) |
isteamuserstats.h | GetNumAchievements/GetAchievementName | 成就枚举 |
数据口径与来源
- 接口签名、回调结构字段(
UserAchievementStored_t的k_iCallback、m_nCurProgress等)、k_cchStatNameMax = 128:SDK v1.65public/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 统计机制 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。