《Steam 游戏平台:开发与商业化》10.1 Depot 与内容分支

内容以 depot 为单位归属,分支指向某个 buildid,GetCurrentBetaName/GetNumBetas/GetBetaInfo/SetActiveBeta 描述客户端可见分支状态。本节讲 depot 归属、分支指向与切换分支需要重启的内容语义,lab 用 C++ mock 验证 depot/分支所有权与切换边界。

10.1 Depot 与内容分支

这一节把「内容」当成分发对象来理解:游戏不是一份单调的大包,而是按 depot(内容单位) 切分、按 分支(branch) 指向某个 buildid 的树。接入工程要同时理解两个归属关系——文件属于哪个 depot、分支指向哪个 buildid——它们决定了灰度、热修与多版本并存的工程边界。

本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamapps.h。

本章与站内既有内容的分工

  • Steam 发行专题 (操作手册)讲「后台创建 depot、配置分支、设置可见性」;本节讲「SDK 里 depot 与分支的可观测接口与内容归属语义」。
  • 卷一《平台机制与商店》讲商店与下载机制;本节把「内容版本」落成 GetCurrentBetaName/GetBetaInfo 的工程口径。
  • lab 用纯 C++ 复现 depot/分支所有权与切换边界,不依赖 Steam 客户端运行。

内容以 depot 为单位:GetInstalledDepots

Steam 客户端把内容拆成多个 depot,接口上客户端能拿到「已安装的 depot 及挂载顺序」:

// isteamapps.h:ISteamApps::GetInstalledDepots(SDK v1.65 头文件摘录,已删减)
virtual uint32 GetInstalledDepots( AppId_t appID, DepotId_t *pvecDepots, uint32 cMaxDepots ) = 0; // return installed depots in mount order

工程语义:

  1. 返回值是已安装 depot 数量,数组按挂载顺序填充:主游戏一个 depot、DLC 一个 depot、测试内容又一个 depot,客户端按此顺序把目录挂载到游戏根。工程上不要把「安装顺序」当「加载优先级」——加载优先级仍是游戏自己定义的。
  2. depot 是分发单元,不是功能单元:拆 depot 的目的是「不同内容不同更新节奏、不同分发可见性」。一个文件只能属于一个 depot,不能跨 depot 共享——这是内容归属的第一条铁律。
  3. GetInstalledDepots 只是读安装态:哪些 depot 当前装了、按什么顺序,客户端以此重建文件布局;「没装全」不代表内容损坏,游戏要用 MarkContentCorrupt 触发 Steam 自检。

分支指向 buildid:GetCurrentBetaName / GetBetaInfo / SetActiveBeta

分支是「buildid 的命名指针」:public 是默认分支,其余 beta 分支各自指向一个 buildid。SDK v1.65 给客户端三个查询/一个设置:

// isteamapps.h:ISteamApps 分支查询与切换(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; // returns total number of known app branches (including default "public" branch ). nAvailable is number of available betas
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; // select this beta branch for this app as active, might need the game to restart so Steam can update to that branch

工程语义:

  1. GetCurrentBetaName 的 ‘public’ 是默认分支:玩家没主动选择分支时,客户端处于 public。工程上做「版本显示」时,‘public’ 与「beta 分支」要分开呈现,避免把默认分支当成 bug。
  2. GetNumBetas 的总数包含 public:头文件注释点名 “including default ‘public’ branch”。pnAvailable 是「玩家可选的 beta 数」,pnPrivate 是「私有测试分支数」——私有分支对普通玩家不可见,但总数仍含它。工程上「给玩家展示几个分支」应读 pnAvailable,而不是总数减一。
  3. GetBetaInfo 是迭代式枚举:按 iBetaIndex 从 0 递增取每个分支的 buildid、名称、描述与最后更新时间。拿 buildid 判断「当前玩的是哪个构建」,就要用当前分支名匹配迭代结果。
  4. SetActiveBeta 可能需要重启游戏才生效:头文件注释明确 “might need the game to restart so Steam can update to that branch”。工程上切换分支后不能立刻假定文件已就位,要检查安装状态并提示重启。
  5. buildid 会变:GetAppBuildId() 注释写 “may change at any time based on backend updates to the game”——不要在启动时缓存 buildid 当作不可变版本号。

depot 与分支的组合:内容归属模型

把两个归属关系合起来,得到一个可验证的模型:

  1. 文件 → depot:每个文件恰好属于一个 depot;一个 depot 被哪些分支引用,决定哪些玩家能见到它的文件。
  2. 分支 → buildid → depot 集合:一个分支指向一个 buildid,buildid 背后是一组 depot 及各自的文件版本。public 分支引用的 depot 少、内容保守;测试分支引用更多 depot,能看到未公开文件。
  3. 切换分支 = 换 buildid = 换 depot 集合:从 public 切到 beta,玩家可见文件集合变化,部分文件在切换前不可见、切换后可见。工程上判断「某文件当前分支是否可见」要按「当前分支 → depot 集合」查,而不是按本地安装态猜。

这就是下面 lab 里 owningDepot(path, branchName) 与 visibleFileCount(branchName) 要验证的语义:内容归属随分支切换而变化,同一文件在不同分支有不同的可见性。

接口签名对照

头文件条目语义
isteamapps.hISteamApps::GetInstalledDepots已安装 depot 及挂载顺序
isteamapps.hISteamApps::GetCurrentBetaName当前分支名(‘public’ 是默认)
isteamapps.hISteamApps::GetNumBetas分支总数(含 public)与可见/私有分支数
isteamapps.hISteamApps::GetBetaInfo迭代取分支详情(buildid/名称/描述/更新时间)
isteamapps.hISteamApps::SetActiveBeta切换活跃分支(可能需要重启)
isteamapps.hISteamApps::GetAppBuildId当前构建 id(随时可变)

数据口径与来源

  • GetCurrentBetaName/GetNumBetas/GetBetaInfo/SetActiveBeta/GetInstalledDepots 签名与注释语义:SDK v1.65 public/steam/isteamapps.h 可实证(本机镜像已核对)。
  • 「每个文件只能属于一个 depot」「分支背后的 buildid 组织」:后台架构概念,partner 文档登录后可见,以官方当前为准;lab 中的 depot/branch 结构为模型。
  • depot 数量上限、分支数量上限等具体配额:官方不公开,本卷不给假设数值。

以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。

可运行产物:C++ 最小验证

下面的仿真复现「Depot 与内容分支」的工程语义:文件按 depot 归属、分支指向 buildid、GetNumBetas/GetBetaInfo 枚举口径、SetActiveBeta 切换与重启标记、内容可见性随分支变化。它与 src/10-1-depot-content-branch.cpp 逐字节一致,mock 接口签名对照 SDK v1.65 头文件:

// file: src/10-1-depot-content-branch.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/10-1-depot-content-branch.cpp -o bin/10-1-depot-content-branch && ./bin/10-1-depot-content-branch
//
// mock:复现 Depot 与内容分支——内容以 depot 为单位归属,分支指向某个 buildid,
// 分支内包含若干 depot;GetCurrentBetaName/GetNumBetas/GetBetaInfo/SetActiveBeta
// 描述分支可见状态;切换分支需要重启游戏。
// 签名对照 SDK v1.65 isteamapps.h,非 Valve 实现。
#include "verify.h"

#include <cstdint>
#include <string>
#include <unordered_map>
#include <vector>

namespace steam_repro {

struct MockFileRec {
  std::string path;
  uint64_t sha1;
  uint64_t sizeBytes;
};

class MockDepot {
 public:
  uint32_t depotId;
  std::unordered_map<std::string, MockFileRec> files;

  bool contains(const std::string& path) const { return files.count(path) > 0; }
};

class MockBranch {
 public:
  std::string name;
  uint32_t buildId;
  std::vector<uint32_t> depotIds;
};

class MockDepotContentBranch {
 public:
  MockDepotContentBranch() {
    branches_ = {
        {"public", 3000, {1, 2}},
        {"beta", 3101, {1, 2, 3}},
        {"private-test", 3202, {1, 2, 3, 4}},
    };
    depots_[1] = MockDepot{1, {{"game.exe", {"game.exe", 0xA1, 40}}, {"res.dat", {"res.dat", 0xB2, 8}}}};
    depots_[2] = MockDepot{2, {{"audio.dat", {"audio.dat", 0xC3, 64}}}};
    depots_[3] = MockDepot{3, {{"beta_content.dat", {"beta_content.dat", 0xD4, 16}}}};
    depots_[4] = MockDepot{4, {{"dev_test.dat", {"dev_test.dat", 0xE5, 4}}}};
  }

  // ISteamApps::GetCurrentBetaName:'public' 是默认分支
  bool getCurrentBetaName(char* pchName, int cchNameBufferSize) {
    std::string n = currentBranch_;
    if (static_cast<int>(n.size()) >= cchNameBufferSize) return false;
    for (size_t i = 0; i <= n.size(); ++i) pchName[i] = n[i];
    return true;
  }

  // ISteamApps::GetNumBetas
  int getNumBetas(int* pnAvailable, int* pnPrivate) {
    int avail = 0, priv = 0;
    for (const auto& b : branches_) {
      if (b.name == "public") continue;
      ++avail;
      priv += (b.name == "private-test") ? 1 : 0;
    }
    if (pnAvailable) *pnAvailable = avail;
    if (pnPrivate) *pnPrivate = priv;
    return static_cast<int>(branches_.size());
  }

  // ISteamApps::GetBetaInfo:迭代取分支(iBetaIndex 为分支序号)
  bool getBetaInfo(int iBetaIndex, uint32_t* punBuildID, std::string* nameOut) {
    if (iBetaIndex < 0 || iBetaIndex >= static_cast<int>(branches_.size())) return false;
    const MockBranch& b = branches_[static_cast<size_t>(iBetaIndex)];
    if (punBuildID) *punBuildID = b.buildId;
    if (nameOut) *nameOut = b.name;
    return true;
  }

  // ISteamApps::SetActiveBeta:切换分支;后续需要重启让 Steam 更新内容
  bool setActiveBeta(const std::string& pchBetaName) {
    for (const auto& b : branches_) {
      if (b.name == pchBetaName) {
        currentBranch_ = pchBetaName;
        needsRestart_ = true;
        return true;
      }
    }
    return false;
  }

  // 内容归属查询:某文件属于哪个 depot(给定分支可见的 depot 集合)
  uint32_t owningDepot(const std::string& path, const std::string& branchName) {
    const MockBranch* br = findBranch(branchName);
    if (!br) return 0;
    for (uint32_t d : br->depotIds) {
      auto it = depots_.find(d);
      if (it != depots_.end() && it->second.contains(path)) return d;
    }
    return 0;
  }

  // 分支指向的 buildid
  uint32_t buildIdOf(const std::string& branchName) const {
    const MockBranch* br = findBranch(branchName);
    return br ? br->buildId : 0;
  }

  // 分支可见的文件数量(用于判断内容归属随分支切换而变化)
  size_t visibleFileCount(const std::string& branchName) const {
    const MockBranch* br = findBranch(branchName);
    if (!br) return 0;
    size_t n = 0;
    for (uint32_t d : br->depotIds) {
      auto it = depots_.find(d);
      if (it != depots_.end()) n += it->second.files.size();
    }
    return n;
  }

  const MockBranch* findBranch(const std::string& name) const {
    for (const auto& b : branches_) {
      if (b.name == name) return &b;
    }
    return nullptr;
  }

  std::string currentBranch_ = "public";
  bool needsRestart_ = false;
  std::vector<MockBranch> branches_;
  std::unordered_map<uint32_t, MockDepot> depots_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockDepotContentBranch m;

  // 1. 默认分支是 public
  char buf[32] = {0};
  CHECK(m.getCurrentBetaName(buf, sizeof(buf)));
  CHECK(std::string(buf) == "public");

  // 2. 内容归属:game.exe 属于 depot 1,audio.dat 属于 depot 2
  CHECK(m.owningDepot("game.exe", "public") == 1);
  CHECK(m.owningDepot("audio.dat", "public") == 2);

  // 3. 未知文件不属于任何 depot
  CHECK(m.owningDepot("missing.dat", "public") == 0);

  // 4. GetNumBetas:总分支数 3(含 public)
  int avail = 0, priv = 0;
  CHECK(m.getNumBetas(&avail, &priv) == 3);
  CHECK(avail == 2);
  CHECK(priv == 1);

  // 5. GetBetaInfo:分支 1(beta)buildid 3101
  uint32_t bid = 0;
  CHECK(m.getBetaInfo(1, &bid, nullptr));
  CHECK(bid == 3101);

  // 6. 不同分支指向不同 buildid
  CHECK(m.buildIdOf("public") == 3000);
  CHECK(m.buildIdOf("beta") == 3101);

  // 7. private-test 分支包含更多 depot → 可见文件更多
  CHECK(m.visibleFileCount("public") == 3);
  CHECK(m.visibleFileCount("beta") == 4);
  CHECK(m.visibleFileCount("private-test") == 5);

  // 8. 分支内容归属:beta_content.dat 只在 beta 分支可见
  CHECK(m.owningDepot("beta_content.dat", "public") == 0);
  CHECK(m.owningDepot("beta_content.dat", "beta") == 3);

  // 9. SetActiveBeta 切换当前分支,标记需要重启
  CHECK(m.setActiveBeta("beta"));
  CHECK(m.needsRestart_);
  CHECK(m.getCurrentBetaName(buf, sizeof(buf)));
  CHECK(std::string(buf) == "beta");

  // 10. 未知分支被拒绝
  CHECK(!m.setActiveBeta("not-a-branch"));
  CHECK(m.buildIdOf("not-a-branch") == 0);

  return lab::report("10-1 Depot 与内容分支");
}

本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 23/23 通过。

小结

  • 内容以 depot 为单位归属,一个文件只能属于一个 depot;GetInstalledDepots 只读安装态与挂载顺序。
  • 分支是 buildid 的命名指针:GetCurrentBetaName 的 ‘public’ 是默认分支,GetNumBetas 总数含 public 与私有分支。
  • SetActiveBeta 切换分支可能需要重启游戏,buildid 随时可变,不要缓存当作不可变版本号。
  • 内容可见性由「当前分支 → buildid → depot 集合」决定,工程上按分支查归属,不按本地安装态猜。

阅读导航:上一节:9.3 服务器架构与商业化 · 下一节:10.2 分发管道与上传 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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