《Steam 游戏平台:开发与商业化》6.2 DLC 所有权与内容

DLC 接入的第一条边界是所有权与内容分离:BIsDlcInstalled 要求拥有授权且内容已安装,BGetDLCDataByIndex 枚举 DLC 元数据,InstallDLC/GetDlcDownloadProgress 管理可选内容下载,DlcInstalled_t 通知会话内购买。本节讲 DLC 所有权接口语义,lab 用 C++ mock 复现「拥有 + 安装」双条件与门控逻辑。

6.2 DLC 所有权与内容

上一节讲了 App 信息机制,这一节处理 DLC 接入的第一条边界:所有权与内容分离。玩家「拥有」一个 DLC 与「能用」一个 DLC 是两件事——拥有是商店侧的授权,能用还要求内容已安装到本机。BIsDlcInstalled 把两个条件折叠成一个布尔,BGetDLCDataByIndex/GetDLCCount 提供元数据枚举,InstallDLC/GetDlcDownloadProgress 管理内容落地,DlcInstalled_t 在会话内购买时把门控翻过去。

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

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

  • Steam 发行专题 (操作手册)讲「在后台建 DLC、配 Depot、上架」;本节讲「代码里判断 DLC 可用的接口语义」。
  • 卷一讲平台机制;本节讲 DLC 所有权与内容在代码里的双条件判断、下载进度与门控。
  • lab 用纯 C++ 复现 DLC 枚举、安装控制与下载进度,不依赖 Steam 客户端运行。

元数据枚举:先数一遍,再逐个读

游戏要在启动时知道「这个用户面对哪些 DLC」,用 GetDLCCount 拿总数、BGetDLCDataByIndex 按索引读元数据。v1.65 签名:

// isteamapps.h:GetDLCCount / BGetDLCDataByIndex / GetEarliestPurchaseUnixTime(SDK v1.65 头文件摘录,已删减)
// Returns the number of DLC pieces for the running app
virtual int GetDLCCount() = 0;
// Returns metadata for DLC by index, of range [0, GetDLCCount()]
virtual bool BGetDLCDataByIndex( int iDLC, AppId_t *pAppID, bool *pbAvailable, char *pchName, int cchNameBufferSize ) = 0;
virtual uint32 GetEarliestPurchaseUnixTime( AppId_t nAppID ) = 0;

工程语义:

  1. 索引范围是 [0, GetDLCCount()):头文件注释明示。遍历时以 GetDLCCount 为界,越界索引返回 false,不要拿固定上限。
  2. pbAvailable 是「商店可用」不是「已拥有」:它回答「这个 DLC 是否已上架」,与「用户是否拥有」正交。未上架但已被内部授权的 DLC,商店不可见但授权仍成立。
  3. BGetDLCDataByIndex 返回的 pchName 是本地化名称:缓冲先探测后填充的惯例再次出现。名称用于「DLC 商店页入口」或「新内容提示」,不是门控依据。

拥有与安装:双条件布尔

BIsDlcInstalled 是接入工程最常用的门控函数。v1.65 注释点名它的双条件:

// isteamapps.h:BIsDlcInstalled / InstallDLC / UninstallDLC / GetDlcDownloadProgress(SDK v1.65 头文件摘录,已删减)
// Takes AppID of DLC and checks if the user owns the DLC & if the DLC is installed
virtual bool BIsDlcInstalled( AppId_t appID ) = 0;
virtual void InstallDLC( AppId_t nAppID ) = 0;
virtual void UninstallDLC( AppId_t nAppID ) = 0;
// get download progress for optional DLC
virtual bool GetDlcDownloadProgress( AppId_t nAppID, uint64 *punBytesDownloaded, uint64 *punBytesTotal ) = 0;

工程语义:

  1. 「拥有」与「已安装」是两个可分离的事实:玩家刚购买但内容还没下完时,BIsDlcInstalled 仍为 false。门控代码不能用「已购买」当「已解锁」,否则会引导玩家进入缺失内容的场景。
  2. InstallDLC 是「可选 DLC」的安装触发:与 DLC 内容绑定在 Depot 的自动安装不同,可选 DLC 需要显式调用。下载进度用 GetDlcDownloadProgress 轮询(注意 punBytesTotal 可能为 0,做百分比前要先判空)。
  3. UninstallDLC 卸载后门控应复位:游戏内的「内容管理」入口卸载一个 DLC 后,BIsDlcInstalled 立刻翻回 false。功能入口要跟随门控而不是跟随「曾安装过」。

会话内购买:DlcInstalled_t 回调

最典型的工程场景是玩家在游戏运行中购买 DLC。v1.65 的 DlcInstalled_t 回调承载「所有权变化 + 内容就绪」的通知:

// isteamapps.h:DlcInstalled_t(SDK v1.65 头文件摘录,已删减)
// Posted after the user gains ownership of DLC & that DLC is installed
struct DlcInstalled_t
{
	enum { k_iCallback = k_iSteamAppsCallbacks + 5 };
	AppId_t m_nAppID;		// AppID of the DLC
};

配套的 SetDlcContext 用于标记「当前正在玩的 DLC」,让 Steam 追踪大型 DLC 扩展的使用:

// isteamapps.h:SetDlcContext(SDK v1.65 头文件摘录,已删减)
// set current DLC AppID being played (or 0 if none). Allows Steam to track usage of major DLC extensions
virtual bool SetDlcContext( AppId_t nAppID ) = 0;

工程语义:

  1. 回调触发时机是「拥有 && 安装」完成后:头文件注释「after the user gains ownership of DLC & that DLC is installed」。这正好补上 BIsDlcInstalled 的翻转点——收到回调后再做 UI 解锁,而不是轮询。
  2. 回调是会话内的:玩家在商店网页购买、回到游戏时 Steam 客户端会同步授权;但「是否触发回调」取决于游戏进程是否在监听。未监听的回调会堆积在回调泵里(第 1 章讲的 RunCallbacks 负责分发)。
  3. SetDlcContext(0) 清空上下文:退出 DLC 内容时调用,避免 Steam 把后续游玩都算进某个 DLC 的使用统计。

接口签名对照

头文件条目语义
isteamapps.hISteamApps::GetDLCCount返回当前 App 的 DLC 数量
isteamapps.hISteamApps::BGetDLCDataByIndex按索引读 DLC 元数据(AppID/可用性/名称)
isteamapps.hISteamApps::BIsDlcInstalled拥有授权 && 内容已安装
isteamapps.hISteamApps::InstallDLC/UninstallDLC可选 DLC 的安装/卸载控制
isteamapps.hISteamApps::GetDlcDownloadProgress可选 DLC 下载进度(字节对)
isteamapps.hISteamApps::SetDlcContext标记当前正在玩的 DLC
isteamapps.hDlcInstalled_t用户获得 DLC 所有权且内容安装完成后的回调

数据口径与来源

  • 接口签名、双条件注释、回调触发时机:SDK v1.65 public/steam/isteamapps.h 可实证(本机镜像已核对)。
  • 具体 DLC 列表、名称、大小、下载配额:partner.steamgames.com 登录后可见,以官方当前为准。
  • 会话内购买的授权同步延迟:Steam 客户端行为,本卷不给假设值,接入工程按回调驱动。

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

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

下面的仿真复现「DLC 所有权与内容」的工程语义:DLC 元数据枚举、BIsDlcInstalled 的「拥有 + 安装」双条件、安装/卸载控制、下载进度、会话内购买回调、SetDlcContext 门控。它与 src/06-2-dlc-ownership-content.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/06-2-dlc-ownership-content.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/06-2-dlc-ownership-content.cpp -o bin/06-2-dlc-ownership-content && ./bin/06-2-dlc-ownership-content
//
// mock:复现 ISteamApps 的 DLC 所有权与内容接口语义——GetDLCCount/BGetDLCDataByIndex
// 元数据枚举、BIsDlcInstalled 的「拥有 + 安装」双条件、InstallDLC/UninstallDLC 内容控制、
// GetDlcDownloadProgress 下载进度、SetDlcContext 使用追踪、DlcInstalled_t 回调语义。
// 签名对照 SDK v1.65 isteamapps.h,非 Valve 实现。
#include "verify.h"

#include <cstdio>
#include <string>
#include <vector>

namespace steam_repro {

// AppId_t 语义:uint32
using MockAppId = uint32_t;

struct MockDLCInfo {
  MockAppId appId = 0;
  bool available = false;  // 商店上架可用(决定 BGetDLCDataByIndex 的 pbAvailable)
  bool owned = false;      // 用户拥有授权
  bool installed = false;  // 本机已安装内容
  std::string name;
  uint64_t bytesDownloaded = 0;
  uint64_t bytesTotal = 0;
  uint32_t purchaseTime = 0;
};

class MockSteamApps {
 public:
  // ISteamApps::GetDLCCount:返回当前 App 的 DLC 数量
  int getDLCCount() const { return static_cast<int>(dlcs_.size()); }

  // ISteamApps::BGetDLCDataByIndex:按索引读 DLC 元数据(AppID、可用性、名称)
  bool bGetDLCDataByIndex(int iDLC, MockAppId* pAppID, bool* pbAvailable,
                          char* pchName, int cchNameBufferSize) {
    if (iDLC < 0 || iDLC >= static_cast<int>(dlcs_.size())) return false;
    const MockDLCInfo& d = dlcs_[static_cast<size_t>(iDLC)];
    if (pAppID) *pAppID = d.appId;
    if (pbAvailable) *pbAvailable = d.available;
    if (pchName && cchNameBufferSize > 0)
      std::snprintf(pchName, static_cast<size_t>(cchNameBufferSize), "%s", d.name.c_str());
    return true;
  }

  // ISteamApps::BIsDlcInstalled:同时要求「拥有授权」与「内容已安装」
  bool bIsDlcInstalled(MockAppId appId) const {
    const MockDLCInfo* d = find(appId);
    return d != nullptr && d->owned && d->installed;
  }

  // ISteamApps::InstallDLC / UninstallDLC:可选 DLC 的安装/卸载控制
  void installDLC(MockAppId appId) {
    MockDLCInfo* d = find(appId);
    if (d && d->owned) {
      d->installed = true;
      d->bytesDownloaded = d->bytesTotal;
    }
  }
  void uninstallDLC(MockAppId appId) {
    MockDLCInfo* d = find(appId);
    if (d) d->installed = false;
  }

  // ISteamApps::GetDlcDownloadProgress:返回可选 DLC 的下载进度
  bool getDlcDownloadProgress(MockAppId appId, uint64_t* punBytesDownloaded,
                              uint64_t* punBytesTotal) const {
    const MockDLCInfo* d = find(appId);
    if (!d) return false;
    if (punBytesDownloaded) *punBytesDownloaded = d->bytesDownloaded;
    if (punBytesTotal) *punBytesTotal = d->bytesTotal;
    return true;
  }

  // ISteamApps::GetEarliestPurchaseUnixTime:购买时间
  uint32_t getEarliestPurchaseUnixTime(MockAppId appId) const {
    const MockDLCInfo* d = find(appId);
    return d ? d->purchaseTime : 0;
  }

  // ISteamApps::SetDlcContext:标记当前正在玩的 DLC(0 表示无),仅对已安装 DLC 有效
  bool setDlcContext(MockAppId appId) {
    if (appId != 0 && !bIsDlcInstalled(appId)) return false;
    currentContext_ = appId;
    return true;
  }
  MockAppId currentContext() const { return currentContext_; }

  // DlcInstalled_t 回调语义:用户在会话中获得 DLC 所有权且内容安装完成后触发。
  // grantDLC 模拟「会话内购买」,返回 true 表示满足回调触发条件。
  bool grantDLC(MockAppId appId) {
    MockDLCInfo* d = find(appId);
    if (!d) return false;
    d->owned = true;
    d->purchaseTime = 1735010000;
    installDLC(appId);  // 拥有即可安装(可选 DLC 由玩家触发安装)
    return true;
  }

  void addDLC(MockAppId appId, const std::string& name, bool available,
              uint64_t bytesTotal) {
    MockDLCInfo d;
    d.appId = appId;
    d.name = name;
    d.available = available;
    d.bytesTotal = bytesTotal;
    dlcs_.push_back(d);
  }

 private:
  MockDLCInfo* find(MockAppId appId) {
    for (auto& d : dlcs_) {
      if (d.appId == appId) return &d;
    }
    return nullptr;
  }
  const MockDLCInfo* find(MockAppId appId) const {
    for (const auto& d : dlcs_) {
      if (d.appId == appId) return &d;
    }
    return nullptr;
  }

  std::vector<MockDLCInfo> dlcs_;
  MockAppId currentContext_ = 0;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamApps apps;
  apps.addDLC(481, "美术设定集", true, 1024 * 1024);
  apps.addDLC(482, "原声带", true, 512 * 1024);
  apps.addDLC(483, "幕后纪录片", false, 2048 * 1024);  // 未上架

  char name[64];
  MockAppId id = 0;
  bool avail = false;

  // 1. GetDLCCount:枚举 DLC 数量
  CHECK(apps.getDLCCount() == 3);

  // 2. BGetDLCDataByIndex:索引 0 读回 AppID/可用性/名称
  CHECK(apps.bGetDLCDataByIndex(0, &id, &avail, name, sizeof(name)));
  CHECK(id == 481);
  CHECK(avail);
  CHECK(std::string(name) == "美术设定集");

  // 3. 未拥有未安装:BIsDlcInstalled 为 false
  CHECK(!apps.bIsDlcInstalled(481));

  // 4. 会话内购买:grantDLC 触发 DlcInstalled_t 条件,BIsDlcInstalled 翻为 true
  CHECK(apps.grantDLC(481));
  CHECK(apps.bIsDlcInstalled(481));

  // 5. 未购买 DLC:仍为 false
  CHECK(!apps.bIsDlcInstalled(482));

  // 6. GetDlcDownloadProgress:已安装内容下载完成,进度字节一致
  uint64_t dl = 0, tot = 0;
  CHECK(apps.getDlcDownloadProgress(481, &dl, &tot));
  CHECK(dl == 1024 * 1024 && tot == 1024 * 1024);

  // 7. UninstallDLC 后 BIsDlcInstalled 翻回 false(内容缺失)
  apps.uninstallDLC(481);
  CHECK(!apps.bIsDlcInstalled(481));
  CHECK(apps.getDlcDownloadProgress(481, &dl, &tot));

  // 8. SetDlcContext:仅对已安装 DLC 可设置;未安装返回 false 且上下文不变
  CHECK(!apps.setDlcContext(481));
  CHECK(apps.currentContext() == 0);
  apps.installDLC(481);
  CHECK(apps.setDlcContext(481));
  CHECK(apps.currentContext() == 481);
  CHECK(apps.setDlcContext(0));  // 清除上下文

  // 9. 未知 DLC 查询失败
  CHECK(!apps.getDlcDownloadProgress(999, &dl, &tot));
  CHECK(!apps.bIsDlcInstalled(999));

  // 10. 未上架 DLC 仍可被授予与安装(可用性影响商店展示,不影响授权)
  CHECK(apps.grantDLC(483));
  CHECK(apps.bIsDlcInstalled(483));

  return lab::report("06-2 DLC 所有权与内容");
}

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

小结

  • BIsDlcInstalled 折叠「拥有 + 安装」两个条件,门控必须用它而不是「已购买」。
  • GetDLCCount/BGetDLCDataByIndex 提供元数据枚举,索引范围 [0, GetDLCCount())。
  • 可选 DLC 用 InstallDLC/UninstallDLC 管理内容,GetDlcDownloadProgress 轮询进度(注意 total 可为 0)。
  • DlcInstalled_t 在「拥有 && 安装」完成后触发,是会话内购买后翻转门控的正确入口。

阅读导航:上一节:6.1 App 信息机制 · 下一节:6.3 DLC 商业策略 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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