1.1 SDK 组成与版本
卷一讲了 Steam 平台的机制全景,这一节开始把视角转到「开发者手里那包东西」:Steamworks SDK。它是一组头文件、库与运行库,头文件定义接口,库在运行时对接 Steam 客户端。开发者的接入工程,本质是「按头文件的契约调用接口、处理回调、把平台数据落进自己的游戏状态」。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。正文摘录的接口签名均对照该版本 public/steam/ 头文件。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「怎么在后台建 App、传构建」;本节讲「SDK 这包东西的组成与接口获取机制」。
- 卷一《平台机制与商店》讲平台机制;本节开始讲机制落进代码的入口——接口从哪来。
- 语言与工具链:本卷 lab 用纯 C++ 复现接口语义,不依赖 Steam 客户端运行。
SDK 的组成
Steamworks SDK 解包后主要分几块:public/(头文件与接口定义)、redistributable_bin/(各平台运行库)、tools/(SteamPipe 等工具)。对游戏工程真正重要的是 public/steam/ 的 44 个头文件——它们定义了全部接口。
头文件分三类:
- 入口头:
steam_api.h(游戏端)、steam_gameserver.h(游戏服务器端)、steam_api_common.h(公共类型)。 - 接口头:
isteamuser.h、isteamuserstats.h、isteamremotestorage.h、isteamugc.h、isteamfriends.h、isteamapps.h、isteaminventory.h、isteamnetworking*.h等,每个接口一个头文件。 - 类型头:
steamclientpublic.h(CSteamID、AppId_t、EResult)、steamtypes.h、matchmakingtypes.h。
接口获取器:接口怎么到手里
游戏代码不直接 new 一个接口,而是通过接口获取器取得。SDK v1.65 的 steam_api_internal.h 用宏生成获取器:
// steam_api_internal.h:STEAM_DEFINE_INTERFACE_ACCESSOR(SDK v1.65 头文件摘录,已删减)
#define STEAM_DEFINE_INTERFACE_ACCESSOR( type, name, expr, kind, version ) \
inline void S_CALLTYPE SteamInternal_Init_ ## name( type *p ) { *p = (type)( expr ); } \
STEAM_CLANG_ATTR( "interface_accessor_kind:" kind ";interface_accessor_version:" version ";" ) \
inline type name() { \
static void* s_CallbackCounterAndContext[ 3 ] = { (void*)&SteamInternal_Init_ ## name, 0, 0 }; \
return *(type*)SteamInternal_ContextInit( s_CallbackCounterAndContext ); \
}
这段宏的工程语义有三个要点:
- 每个接口按「名字 + 版本字符串」注册(宏的
name与version参数)。Steam 客户端实际版本不匹配时,获取器可以拒绝返回,这是「接口版本协商」的实现基础。 - lazy 初始化 + 线程局部缓存:
static void* s_CallbackCounterAndContext[3]是函数内静态状态,首次调用时通过SteamInternal_ContextInit找到接口实例,之后直接返回缓存。同一线程反复调用SteamUser()拿到的是同一个实例,不会重复创建。 - 接口实例的获取是「查询」不是「构造」:接口实例由 Steam 客户端侧提供,游戏侧只是拿指针。所以获取器可能返回空(客户端版本不兼容或初始化失败),接入工程必须处理空指针。
理解这段宏,就理解了卷二后面所有 SteamUser()、SteamUserStats() 调用的共同前提:先注册/版本协商,再 lazy 取得单例,用后随进程生命周期走。
版本口径:为什么锚定 v1.65
SDK 每个接口版本字符串随发布演进(如 SteamUser012)。写本卷时镜像到的最新发布是 v1.65(2026-07-23),其 Readme 记录了本轮变更:例如 ISteamUtils::IsRunningOnSteamDeck() 移除、新增 IsRunningOnSteamHardware() 返回 ESteamHardwareType。这意味着接口不是永恒不变的:正文摘录的签名只保证对 v1.65 成立,实现接入时应以自己拿到的 SDK 版本为准。这也是 lab 里 mock 注册表带上「版本字符串」的原因——机制上版本即契约。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
steam_api.h | SteamAPI_Init()/InitEx()/Shutdown()/RunCallbacks() | 生命周期入口 |
steam_api_internal.h | STEAM_DEFINE_INTERFACE_ACCESSOR | 接口获取器生成宏 |
public/steam/ 各 isteam*.h | virtual …() = 0; 接口声明 | 各功能接口 |
steam_api_common.h | S_API 链接约定 | 跨平台导出/导入 |
数据口径与来源
- 头文件组成与接口获取器宏:SDK v1.65
public/steam/头文件可实证(本机镜像已核对)。 - 版本发布与变更明细:SDK Readme(v1.65, 2026-07-23)。
- 运行库
redistributable_bin/与tools/的具体分发:写入时以官方 SDK 包为准(登录 partner 后可下载)。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「接口获取器」的工程语义:按「接口名 + 版本」注册、首次调用 lazy 创建、重复调用返回同一实例、未注册接口返回空指针。它与 src/01-1-sdk-components-version.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:
// file: src/01-1-sdk-components-version.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/01-1-sdk-components-version.cpp -o bin/01-1-sdk-components-version && ./bin/01-1-sdk-components-version
//
// mock:复现 Steamworks SDK 接口获取器(STEAM_DEFINE_INTERFACE_ACCESSOR)语义——
// 按「接口名+版本」注册、首次调用 lazy 创建、重复调用返回同一实例、未注册返回空。
// 签名对照 SDK v1.65 steam_api_internal.h 宏,非 Valve 实现。
#include "verify.h"
#include <string>
#include <unordered_map>
namespace steam_repro {
struct MockInterface {
std::string name;
std::string version;
int refs = 0; // 被获取次数
};
// mock 接口注册表:接口名 -> (版本, 单例实例)
class MockAccessor {
public:
// 注册接口;空名/空版本注册失败
bool registerInterface(const std::string& name, const std::string& version) {
if (name.empty() || version.empty()) return false;
instances_[name] = {name, version, 0};
return true;
}
// 获取接口:未注册返回 nullptr;已注册返回同一实例(首次 lazy 创建)
MockInterface* get(const std::string& name) {
auto it = instances_.find(name);
if (it == instances_.end()) return nullptr;
++it->second.refs;
return &it->second;
}
// 版本查询:未注册返回空串(对应版本不匹配时的拒绝路径)
std::string versionOf(const std::string& name) {
auto it = instances_.find(name);
return it == instances_.end() ? "" : it->second.version;
}
private:
std::unordered_map<std::string, MockInterface> instances_;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockAccessor api;
// 1. 注册两个接口(模拟 SteamUser / SteamUserStats 获取器)
CHECK(api.registerInterface("SteamUser", "SteamUser012"));
CHECK(api.registerInterface("SteamUserStats", "SteamUserStats012"));
// 2. 空名 / 空版本注册失败
CHECK(!api.registerInterface("", "v"));
CHECK(!api.registerInterface("SteamApps", ""));
// 3. 首次获取 lazy 创建实例
MockInterface* a1 = api.get("SteamUser");
CHECK(a1 != nullptr);
CHECK(a1->refs == 1);
// 4. 再次获取返回同一实例
MockInterface* a2 = api.get("SteamUser");
CHECK(a1 == a2);
CHECK(a1->refs == 2);
// 5. 未注册接口返回空指针(版本协商失败路径)
CHECK(api.get("SteamFriends") == nullptr);
CHECK(api.versionOf("SteamFriends") == "");
// 6. 已注册接口版本可查
CHECK(api.versionOf("SteamUser") == "SteamUser012");
// 7. 统计接口独立实例,不串扰
MockInterface* s1 = api.get("SteamUserStats");
CHECK(s1 != nullptr);
CHECK(s1 != a1);
CHECK(api.get("SteamUserStats") == s1);
CHECK(a1->refs == 2);
CHECK(s1->refs == 2);
// 8. 各接口版本不同(版本即契约)
CHECK(api.versionOf("SteamUser") != api.versionOf("SteamUserStats"));
return lab::report("01-1 SDK 组成与版本");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 17/17 通过。
小结
- Steamworks SDK 的契约在
public/steam/头文件里:入口头、接口头、类型头三类。 - 接口获取器(
STEAM_DEFINE_INTERFACE_ACCESSOR)按「名字 + 版本」注册,lazy 取得线程局部单例,未注册/版本不匹配返回空。 - 版本即契约:SDK 接口随版本演进(v1.65 移除/新增多个
ISteamUtils方法),正文摘录只对 v1.65 成立。 - 接入工程的前提:处理好获取器空指针与版本协商,再谈功能。
阅读导航:上一节:卷一目录 · 下一节:1.2 初始化与运行循环 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。