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;
工程语义:
- 索引范围是
[0, GetDLCCount()):头文件注释明示。遍历时以GetDLCCount为界,越界索引返回 false,不要拿固定上限。 pbAvailable是「商店可用」不是「已拥有」:它回答「这个 DLC 是否已上架」,与「用户是否拥有」正交。未上架但已被内部授权的 DLC,商店不可见但授权仍成立。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;
工程语义:
- 「拥有」与「已安装」是两个可分离的事实:玩家刚购买但内容还没下完时,
BIsDlcInstalled仍为 false。门控代码不能用「已购买」当「已解锁」,否则会引导玩家进入缺失内容的场景。 InstallDLC是「可选 DLC」的安装触发:与 DLC 内容绑定在 Depot 的自动安装不同,可选 DLC 需要显式调用。下载进度用GetDlcDownloadProgress轮询(注意punBytesTotal可能为 0,做百分比前要先判空)。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;
工程语义:
- 回调触发时机是「拥有 && 安装」完成后:头文件注释「after the user gains ownership of DLC & that DLC is installed」。这正好补上
BIsDlcInstalled的翻转点——收到回调后再做 UI 解锁,而不是轮询。 - 回调是会话内的:玩家在商店网页购买、回到游戏时 Steam 客户端会同步授权;但「是否触发回调」取决于游戏进程是否在监听。未监听的回调会堆积在回调泵里(第 1 章讲的 RunCallbacks 负责分发)。
SetDlcContext(0)清空上下文:退出 DLC 内容时调用,避免 Steam 把后续游玩都算进某个 DLC 的使用统计。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamapps.h | ISteamApps::GetDLCCount | 返回当前 App 的 DLC 数量 |
isteamapps.h | ISteamApps::BGetDLCDataByIndex | 按索引读 DLC 元数据(AppID/可用性/名称) |
isteamapps.h | ISteamApps::BIsDlcInstalled | 拥有授权 && 内容已安装 |
isteamapps.h | ISteamApps::InstallDLC/UninstallDLC | 可选 DLC 的安装/卸载控制 |
isteamapps.h | ISteamApps::GetDlcDownloadProgress | 可选 DLC 下载进度(字节对) |
isteamapps.h | ISteamApps::SetDlcContext | 标记当前正在玩的 DLC |
isteamapps.h | DlcInstalled_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 商业策略 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。