6.1 App 信息机制
上一节讲了覆盖层的产品意义,这一节转向一个更「底层」的接口域:App 信息。ISteamApps 是游戏读取自身安装事实的窗口——装在哪个目录、跑在哪个 Beta 分支、内容是否齐全、当前用户是不是借用来的、用哪个构建号起的进程。这些信息不像成就、DLC 那样是「内容」,但它们的工程语义恰恰决定了接入工程能不能正确判断「我现在处于什么环境」。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamapps.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「在后台建 App、配分支、传 Depot」;本节讲「代码里读取这些配置的接口语义」。
- 卷一讲平台机制;本节讲 App 信息怎么落进代码——安装目录解析、分支枚举、家庭共享借用识别。
- lab 用纯 C++ 复现 ISteamApps 的信息读取面,不依赖 Steam 客户端运行。
安装目录:内容在磁盘上的位置
GetAppInstallDir 解决「游戏的内容装在哪」:传入 AppID 与缓冲,返回目录名长度。v1.65 的签名:
// isteamapps.h:GetAppInstallDir / GetInstalledDepots / MarkContentCorrupt(SDK v1.65 头文件摘录,已删减)
// returns current app install folder for AppID, returns folder name length
virtual uint32 GetAppInstallDir( AppId_t appID, char *pchFolder, uint32 cchFolderBufferSize ) = 0;
virtual uint32 GetInstalledDepots( AppId_t appID, DepotId_t *pvecDepots, uint32 cMaxDepots ) = 0; // return installed depots in mount order
virtual bool MarkContentCorrupt( bool bMissingFilesOnly ) = 0; // signal Steam that game files seems corrupt or missing
工程语义有三个要点:
- 「先探测、后填充」是缓冲惯例:先传空指针拿所需长度,再分配足量缓冲;缓冲不足时函数返回所需长度而不截断。App 信息类接口普遍采用这一惯例,接入工程应统一封装。
- 返回长度是文件夹名长度:头文件注释明确「returns folder name length」,不含结尾
'\0'。做字符串处理时不要重复叠加。 - 未安装的 App 返回 0:
GetAppInstallDir对未安装的 AppID 返回 0,是「内容不完整」的显式信号;配合MarkContentCorrupt可以在启动校验发现文件缺失时通知 Steam 重新校验。
Beta 分支:分支名是运行期事实
玩家跑在哪个分支不是「配置」,而是运行期可查询的事实。GetCurrentBetaName 返回当前分支名,默认分支固定为 'public';GetNumBetas/GetBetaInfo 枚举全部已知分支,SetActiveBeta 切换激活分支。v1.65 签名:
// isteamapps.h:GetCurrentBetaName / GetNumBetas / GetBetaInfo / SetActiveBeta(SDK v1.65 头文件摘录,已删减)
virtual bool GetCurrentBetaName( char *pchName, int cchNameBufferSize ) = 0; // returns current beta branch name, 'public' is the default branch
virtual int GetNumBetas( int *pnAvailable, int *pnPrivate ) = 0; //
virtual bool GetBetaInfo( int iBetaIndex, uint32 *punFlags, uint32 *punBuildID, char *pchBetaName, int cchBetaName, char *pchDescription, int cchDescription, uint32 *punLastUpdated ) = 0; // iterate through
virtual bool SetActiveBeta( const char *pchBetaName ) = 0;
工程语义:
- 分支名直接决定兼容口径:
beta-1.1与public可能对应不同的内容版本。遥测系统应在启动时记录分支名,Mod 兼容性检查也应把分支名纳入版本判定(第 7 章创意工坊的SetRequiredGameVersions正是按分支范围匹配)。 GetBetaInfo一次只读一个分支:通过索引遍历(GetNumBetas给出上限)。每个分支携带BuildID与LastUpdated,适合做「这个分支更新到哪了」的展示。SetActiveBeta可能要求重启:切换分支通常需要 Steam 先更新内容,头文件注释「might need the game to restart so Steam can update to that branch」。因此切换是「用户决策」而非「运行中热切」。
拥有者、构建号与启动参数
BIsAppInstalled 判断安装、GetAppOwner 返回原拥有者、GetAppBuildId 返回构建号、GetLaunchQueryParam 读取 steam://run 启动参数。v1.65 签名:
// isteamapps.h:BIsAppInstalled / GetAppOwner / GetAppBuildId / GetLaunchQueryParam(SDK v1.65 头文件摘录,已删减)
virtual bool BIsAppInstalled( AppId_t appID ) = 0; // returns true if that app is installed (not necessarily owned)
virtual CSteamID GetAppOwner() = 0;
// Returns the associated launch param if the game is run via steam://run/<appid>//?param1=value1¶m2=value2¶m3=value3 etc.
virtual const char *GetLaunchQueryParam( const char *pchKey ) = 0;
virtual int GetAppBuildId() = 0;
工程语义:
- 家庭共享借用 = 拥有者与登录者不同:头文件注释点名——「If this CSteamID is different from ISteamUser::GetSteamID(), the user has a temporary license borrowed via Family Sharing」。借用玩家不该看到「购买」入口,DLC 门控也要按借用的授权集合判断。
GetAppBuildId是遥测基线:同一分支下构建号还会随后端更新变化(头文件注释「may change at any time based on backend updates to the game」),崩溃报告与日志必须带上它,才能区分「老版本崩了」与「新版本崩了」。- 启动参数是安全的联机入口:
GetLaunchQueryParam只读steam://run/<appid>//?形式参数,比从操作系统命令行解析更安全(头文件注释明示 OS 命令行是安全风险)。参数名以@开头的为内部保留、_开头为 Steam 功能保留,自定义参数应避免这两个前缀。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamapps.h | ISteamApps::GetAppInstallDir | 返回 App 安装目录名长度(未安装返回 0) |
isteamapps.h | ISteamApps::GetCurrentBetaName | 返回当前 Beta 分支名(默认 'public') |
isteamapps.h | ISteamApps::GetNumBetas / GetBetaInfo | 枚举已知分支及其 BuildID/更新时间 |
isteamapps.h | ISteamApps::SetActiveBeta | 切换激活分支(可能需重启) |
isteamapps.h | ISteamApps::BIsAppInstalled | 该 App 是否已安装(不要求拥有) |
isteamapps.h | ISteamApps::GetAppOwner | 原拥有者 SteamID(家庭共享识别) |
isteamapps.h | ISteamApps::GetAppBuildId | 当前构建号 |
isteamapps.h | ISteamApps::GetLaunchQueryParam | 读取 steam://run 启动查询参数 |
数据口径与来源
- 接口签名、
'public'默认分支、返回长度语义、家庭共享识别说明:SDK v1.65public/steam/isteamapps.h可实证(本机镜像已核对)。 - 「切换分支可能需重启」「
@/_参数前缀保留」:头文件注释明文。 - 各分支名称与构建号是发行配置:partner.steamgames.com 登录后可见,以官方当前为准。
- 「低档位转化率更高」等商业数字:本节不涉及,商业口径见 6.3 与卷一的定价章节。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「App 信息机制」的工程语义:安装目录解析(含缓冲探测)、当前分支、分支枚举与切换、是否安装、拥有者、构建号、启动查询参数。它与 src/06-1-appinfo-mechanics.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:
// file: src/06-1-appinfo-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/06-1-appinfo-mechanics.cpp -o bin/06-1-appinfo-mechanics && ./bin/06-1-appinfo-mechanics
//
// mock:复现 ISteamApps 的 App 信息接口语义——安装目录解析、当前 Beta 分支、
// App 是否安装、拥有者(家庭共享)、BuildId、Beta 分支枚举与切换、启动查询参数。
// 签名对照 SDK v1.65 isteamapps.h,非 Valve 实现。
#include "verify.h"
#include <cstdio>
#include <cstring>
#include <map>
#include <set>
#include <string>
#include <vector>
namespace steam_repro {
// AppId_t 语义:uint32
using MockAppId = uint32_t;
struct MockBetaInfo {
std::string name;
std::string description;
uint32_t buildId = 0;
uint32_t flags = 0;
uint32_t lastUpdated = 0;
};
class MockSteamApps {
public:
MockSteamApps() {
betas_ = {
{"public", "默认分支", 4102, 0, 1735000000},
{"beta-1.1", "性能测试分支", 4120, 0, 1735000100},
{"private-dev", "内部开发分支", 4135, 0, 1735000200},
};
}
// ISteamApps::GetAppInstallDir:返回 App 安装目录名长度;缓冲不足或未安装时按头文件语义处理。
// 对照 isteamapps.h:GetAppInstallDir
uint32_t getAppInstallDir(MockAppId appId, char* pchFolder, uint32_t cchFolderBufferSize) {
if (installed_.count(appId) == 0) return 0;
const std::string& dir = installDir_;
uint32_t need = static_cast<uint32_t>(dir.size() + 1);
if (pchFolder == nullptr || cchFolderBufferSize < need) return need;
std::memcpy(pchFolder, dir.c_str(), need);
return need - 1; // 返回文件夹名长度(不含结尾 '\0')
}
// ISteamApps::GetCurrentBetaName:写入当前分支名,'public' 为默认分支
bool getCurrentBetaName(char* pchName, int cchNameBufferSize) {
if (pchName == nullptr || cchNameBufferSize <= 0) return false;
std::snprintf(pchName, static_cast<size_t>(cchNameBufferSize), "%s", activeBeta_.c_str());
return true;
}
// ISteamApps::BIsAppInstalled:该 App 是否已安装(不要求已拥有)
bool bIsAppInstalled(MockAppId appId) const { return installed_.count(appId) > 0; }
// ISteamApps::GetAppOwner:原拥有者 SteamID;与当前登录者不同 → 家庭共享借用
uint64_t getAppOwner() const { return ownerSteamId_; }
void setOwnerSteamId(uint64_t id) { ownerSteamId_ = id; }
// ISteamApps::GetAppBuildId:返回当前构建号
int getAppBuildId() const { return buildId_; }
void setBuildId(int id) { buildId_ = id; }
// ISteamApps::GetNumBetas:返回已知分支总数,pnAvailable/pnPrivate 输出可用/私有数
int getNumBetas(int* pnAvailable, int* pnPrivate) const {
if (pnAvailable) *pnAvailable = static_cast<int>(betas_.size());
if (pnPrivate) *pnPrivate = 1; // 模型假设:末位为私有分支
return static_cast<int>(betas_.size());
}
// ISteamApps::GetBetaInfo:按索引读分支详情(名称/描述/构建号/更新时刻)
bool getBetaInfo(int iBetaIndex, uint32_t* punFlags, uint32_t* punBuildID,
char* pchBetaName, int cchBetaName, char* pchDescription,
int cchDescription, uint32_t* punLastUpdated) {
if (iBetaIndex < 0 || iBetaIndex >= static_cast<int>(betas_.size())) return false;
const MockBetaInfo& b = betas_[static_cast<size_t>(iBetaIndex)];
if (punFlags) *punFlags = b.flags;
if (punBuildID) *punBuildID = b.buildId;
if (pchBetaName && cchBetaName > 0)
std::snprintf(pchBetaName, static_cast<size_t>(cchBetaName), "%s", b.name.c_str());
if (pchDescription && cchDescription > 0)
std::snprintf(pchDescription, static_cast<size_t>(cchDescription), "%s", b.description.c_str());
if (punLastUpdated) *punLastUpdated = b.lastUpdated;
return true;
}
// ISteamApps::SetActiveBeta:切换当前分支
bool setActiveBeta(const char* pchBetaName) {
for (const MockBetaInfo& b : betas_) {
if (b.name == pchBetaName) {
activeBeta_ = b.name;
return true;
}
}
return false;
}
// ISteamApps::GetLaunchQueryParam:读 steam://run/<appid>//?param 启动参数,未命中返回空串
const char* getLaunchQueryParam(const char* pchKey) {
auto it = launchParams_.find(std::string(pchKey));
if (it == launchParams_.end()) return "";
return it->second.c_str();
}
void markInstalled(MockAppId appId) { installed_.insert(appId); }
void setLaunchParam(const std::string& k, const std::string& v) { launchParams_[k] = v; }
const std::string& activeBeta() const { return activeBeta_; }
private:
std::vector<MockBetaInfo> betas_;
std::string activeBeta_ = "public";
std::string installDir_ = "/opt/steamapps/common/plumephp";
std::set<MockAppId> installed_;
uint64_t ownerSteamId_ = 76561197960287930ull;
int buildId_ = 4102;
std::map<std::string, std::string> launchParams_;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockSteamApps apps;
apps.markInstalled(480);
apps.setLaunchParam("lobby", "abc123");
char buf[128];
// 1. BIsAppInstalled:已安装 App 返回 true
CHECK(apps.bIsAppInstalled(480));
// 2. GetAppInstallDir:已安装 App 返回目录长度并写入路径
uint32_t len = apps.getAppInstallDir(480, buf, sizeof(buf));
CHECK(len > 0);
CHECK(std::string(buf).find("plumephp") != std::string::npos);
// 3. 未安装 App:BIsAppInstalled 与 GetAppInstallDir 均为空
CHECK(!apps.bIsAppInstalled(481));
CHECK(apps.getAppInstallDir(481, buf, sizeof(buf)) == 0);
// 4. 缓冲不足:返回所需长度而非截断(先探测长度惯例)
char tiny[4];
uint32_t need = apps.getAppInstallDir(480, nullptr, 0);
CHECK(need > sizeof(tiny));
CHECK(apps.getAppInstallDir(480, tiny, sizeof(tiny)) == need);
// 5. GetCurrentBetaName:默认分支为 public
CHECK(apps.getCurrentBetaName(buf, sizeof(buf)));
CHECK(std::string(buf) == "public");
// 6. GetNumBetas:枚举全部分支
int avail = 0, priv = 0;
CHECK(apps.getNumBetas(&avail, &priv) == 3);
CHECK(avail == 3);
// 7. GetBetaInfo:按索引读回分支名与描述
CHECK(apps.getBetaInfo(1, nullptr, nullptr, buf, sizeof(buf), nullptr, 0, nullptr));
CHECK(std::string(buf) == "beta-1.1");
// 8. SetActiveBeta 切换后 GetCurrentBetaName 跟随变化
CHECK(apps.setActiveBeta("beta-1.1"));
CHECK(apps.getCurrentBetaName(buf, sizeof(buf)));
CHECK(std::string(buf) == "beta-1.1");
// 9. 不存在的分支切换失败,保持原分支
CHECK(!apps.setActiveBeta("no-such-branch"));
CHECK(apps.activeBeta() == "beta-1.1");
// 10. GetAppBuildId / GetAppOwner(家庭共享场景:owner 与当前登录者不同)
CHECK(apps.getAppBuildId() == 4102);
CHECK(apps.getAppOwner() == 76561197960287930ull);
apps.setOwnerSteamId(76561197999999999ull);
CHECK(apps.getAppOwner() != 76561197960287930ull);
// 11. GetLaunchQueryParam:命中返回参数,未命中返回空串
CHECK(std::string(apps.getLaunchQueryParam("lobby")) == "abc123");
CHECK(std::string(apps.getLaunchQueryParam("missing")) == "");
return lab::report("06-1 App 信息机制");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 23/23 通过。
小结
GetAppInstallDir遵循「先探测、后填充」的缓冲惯例,未安装返回 0;返回长度不含结尾'\0'。- 分支名是运行期事实:
GetCurrentBetaName读当前分支,GetNumBetas/GetBetaInfo枚举全部,SetActiveBeta切换(可能需重启)。 GetAppOwner与ISteamUser::GetSteamID()不同即家庭共享借用,是授权判断的边界。GetAppBuildId是遥测基线;GetLaunchQueryParam提供比 OS 命令行更安全的联机入口。
阅读导航:上一节:5.3 覆盖层的产品意义 · 下一节:6.2 DLC 所有权与内容 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。