《Steam 游戏平台:开发与商业化》6.1 App 信息机制

ISteamApps 是游戏读取自身安装事实的窗口:GetAppInstallDir 解析安装目录、GetCurrentBetaName 读取当前 Beta 分支、GetAppOwner 识别家庭共享借用、GetLaunchQueryParam 读取启动参数。本节讲 App 信息接口的工程语义,lab 用 C++ mock 复现安装目录、分支枚举与启动参数解析逻辑。

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

工程语义有三个要点:

  1. 「先探测、后填充」是缓冲惯例:先传空指针拿所需长度,再分配足量缓冲;缓冲不足时函数返回所需长度而不截断。App 信息类接口普遍采用这一惯例,接入工程应统一封装。
  2. 返回长度是文件夹名长度:头文件注释明确「returns folder name length」,不含结尾 '\0'。做字符串处理时不要重复叠加。
  3. 未安装的 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;

工程语义:

  1. 分支名直接决定兼容口径:beta-1.1 与 public 可能对应不同的内容版本。遥测系统应在启动时记录分支名,Mod 兼容性检查也应把分支名纳入版本判定(第 7 章创意工坊的 SetRequiredGameVersions 正是按分支范围匹配)。
  2. GetBetaInfo 一次只读一个分支:通过索引遍历(GetNumBetas 给出上限)。每个分支携带 BuildID 与 LastUpdated,适合做「这个分支更新到哪了」的展示。
  3. 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&param2=value2&param3=value3 etc.
virtual const char *GetLaunchQueryParam( const char *pchKey ) = 0;
virtual int GetAppBuildId() = 0;

工程语义:

  1. 家庭共享借用 = 拥有者与登录者不同:头文件注释点名——「If this CSteamID is different from ISteamUser::GetSteamID(), the user has a temporary license borrowed via Family Sharing」。借用玩家不该看到「购买」入口,DLC 门控也要按借用的授权集合判断。
  2. GetAppBuildId 是遥测基线:同一分支下构建号还会随后端更新变化(头文件注释「may change at any time based on backend updates to the game」),崩溃报告与日志必须带上它,才能区分「老版本崩了」与「新版本崩了」。
  3. 启动参数是安全的联机入口:GetLaunchQueryParam 只读 steam://run/<appid>//? 形式参数,比从操作系统命令行解析更安全(头文件注释明示 OS 命令行是安全风险)。参数名以 @ 开头的为内部保留、_ 开头为 Steam 功能保留,自定义参数应避免这两个前缀。

接口签名对照

头文件条目语义
isteamapps.hISteamApps::GetAppInstallDir返回 App 安装目录名长度(未安装返回 0)
isteamapps.hISteamApps::GetCurrentBetaName返回当前 Beta 分支名(默认 'public')
isteamapps.hISteamApps::GetNumBetas / GetBetaInfo枚举已知分支及其 BuildID/更新时间
isteamapps.hISteamApps::SetActiveBeta切换激活分支(可能需重启)
isteamapps.hISteamApps::BIsAppInstalled该 App 是否已安装(不要求拥有)
isteamapps.hISteamApps::GetAppOwner原拥有者 SteamID(家庭共享识别)
isteamapps.hISteamApps::GetAppBuildId当前构建号
isteamapps.hISteamApps::GetLaunchQueryParam读取 steam://run 启动查询参数

数据口径与来源

  • 接口签名、'public' 默认分支、返回长度语义、家庭共享识别说明:SDK v1.65 public/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 所有权与内容 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图