7.2 UGC 内容管道
7.1 讲条目怎么被创建出来,这一节讲玩家侧怎么把条目用起来:查询、订阅、下载、安装。玩家打开创意工坊页时,游戏先发一个查询;玩家点「订阅」后,条目内容开始落地;游戏从磁盘读取内容时,要能区分「还没装」「在下载」「装好了但可更新」。这段管道的每一段都有对应的 ISteamUGC 接口。
本卷所有接口口径以 Steamworks SDK v1.65(2026-07-23) 为准。本节摘录的签名对照该版本 public/steam/isteamugc.h。
本章与站内既有内容的分工
- Steam 发行专题 (操作手册)讲「后台配创意工坊可见性与标签」;本节讲「查询、订阅、下载的接口管道语义」。
- 7.1 讲创建条目(创作者侧);本节讲消费条目(玩家侧)——查询句柄生命周期、订阅与安装状态位。
- lab 用纯 C++ 复现查询句柄生命周期与「订阅 → 下载 → 安装」状态迁移,不依赖 Steam 客户端运行。
查询:句柄生命周期
游戏要展示「有哪些条目」,先创建查询句柄、发送、读结果、最后释放。v1.65 的查询四件套:
// isteamugc.h:CreateQueryAllUGCRequest / SendQueryUGCRequest / GetQueryUGCResult / ReleaseQueryUGCRequest(SDK v1.65 头文件摘录,已删减)
virtual UGCQueryHandle_t CreateQueryAllUGCRequest( EUGCQuery eQueryType, EUGCMatchingUGCType eMatchingeMatchingUGCTypeFileType, AppId_t nCreatorAppID, AppId_t nConsumerAppID, uint32 unPage ) = 0;
virtual SteamAPICall_t SendQueryUGCRequest( UGCQueryHandle_t handle ) = 0;
virtual bool GetQueryUGCResult( UGCQueryHandle_t handle, uint32 index, SteamUGCDetails_t *pDetails ) = 0;
virtual bool ReleaseQueryUGCRequest( UGCQueryHandle_t handle ) = 0;
工程语义:
- 查询句柄是显式资源:创建到释放是完整生命周期。
ReleaseQueryUGCRequest之后句柄不可再用,接入工程要用 RAII 包装句柄,防止查询泄漏。 SendQueryUGCRequest是异步的:返回SteamAPICall_t,结果经SteamUGCQueryCompleted_t回调到达(回调里的m_unNumResultsReturned是本次返回的条数)。mock 里为了可验证做了同步返回,但接入工程必须按回调驱动。- 结果是「游标 + 按索引读」:
GetQueryUGCResult(handle, index, &details)按索引读取。遍历边界是回调给出的返回条数,越界索引返回 false;分页由unPage(从 1 起)控制,不要自己假设每页大小。
订阅与下载:状态位推进
玩家订阅后,条目进入本机内容管道。v1.65 的订阅与下载接口:
// isteamugc.h:SubscribeItem / GetNumSubscribedItems / GetSubscribedItems / DownloadItem / GetItemInstallInfo / GetItemDownloadInfo(SDK v1.65 头文件摘录,已删减)
virtual SteamAPICall_t SubscribeItem( PublishedFileId_t nPublishedFileID ) = 0; // subscribe to this item, will be installed ASAP
virtual uint32 GetNumSubscribedItems( bool bIncludeLocallyDisabled = false ) = 0; // number of subscribed items
virtual uint32 GetSubscribedItems( PublishedFileId_t* pvecPublishedFileID, uint32 cMaxEntries, bool bIncludeLocallyDisabled = false ) = 0; // all subscribed item PublishFileIDs
virtual uint32 GetItemState( PublishedFileId_t nPublishedFileID ) = 0;
virtual bool GetItemInstallInfo( PublishedFileId_t nPublishedFileID, uint64 *punSizeOnDisk, STEAM_OUT_STRING_COUNT( cchFolderSize ) char *pchFolder, uint32 cchFolderSize, uint32 *punTimeStamp ) = 0;
virtual bool GetItemDownloadInfo( PublishedFileId_t nPublishedFileID, uint64 *punBytesDownloaded, uint64 *punBytesTotal ) = 0;
virtual bool DownloadItem( PublishedFileId_t nPublishedFileID, bool bHighPriority ) = 0;
工程语义:
SubscribeItem不是「立即下载」:头文件注释「will be installed ASAP」。订阅建立关系,内容落地由 SDK 排队处理;DownloadItem(..., bHighPriority)可提高优先级。两者都经异步回调(DownloadItemResult_t)确认结果。- 「已订阅」与「已安装」用状态位分开:
GetItemState返回位标志。判断内容可用要检查Installed位;订阅列表(GetSubscribedItems)不等于已安装列表。 - 安装信息带显式目录:
GetItemInstallInfo输出磁盘路径与大小。注意punSizeOnDisk的目录是内容在创意工坊下载目录下的相对路径,读取条目前要检查该接口的返回值——未安装时返回 false。 - 下载进度对是「已下 / 总量」:
GetItemDownloadInfo输出字节对。总量可能为 0(尚未开始传输),做百分比前先判空,与 6.2 的 DLC 下载进度同一惯例。
状态迁移的完整窗口
一个条目从订阅到可用,状态位依次出现:Subscribed → Subscribed|Downloading|DownloadPending → Subscribed|Installed。如果创作者发布新版本,还会叠加 NeedsUpdate。接入工程要注意三个时间窗:
- 订阅但未下载:条目在订阅列表里,但
GetItemState没有Installed位,GetItemInstallInfo返回 false。此时创意工坊菜单显示「下载中/未安装」,不加载内容。 - 下载进行中:
Downloading|DownloadPending位存在,进度对持续更新。此时玩家可能切去别的地方,回来时内容可用。 - 已安装但可更新:
Installed位存在,但叠加NeedsUpdate。游戏应继续用旧版内容,同时后台推进更新,而不是中断玩家。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamugc.h | ISteamUGC::CreateQueryAllUGCRequest | 创建全量查询句柄(分页从 1 起) |
isteamugc.h | ISteamUGC::SendQueryUGCRequest | 发送查询(异步,经 SteamUGCQueryCompleted_t 回调) |
isteamugc.h | ISteamUGC::GetQueryUGCResult | 按索引读查询结果(SteamUGCDetails_t) |
isteamugc.h | ISteamUGC::ReleaseQueryUGCRequest | 释放查询句柄 |
isteamugc.h | ISteamUGC::SubscribeItem | 订阅条目(异步) |
isteamugc.h | ISteamUGC::GetNumSubscribedItems/GetSubscribedItems | 订阅列表读取 |
isteamugc.h | ISteamUGC::DownloadItem | 触发内容下载(可加急) |
isteamugc.h | ISteamUGC::GetItemInstallInfo | 已安装条目的磁盘路径与大小 |
isteamugc.h | ISteamUGC::GetItemDownloadInfo | 下载进度(已下/总量) |
isteamugc.h | ISteamUGC::GetItemState | 条目状态位(订阅/安装/下载中…) |
数据口径与来源
- 接口签名、分页参数、回调字段、状态位含义:SDK v1.65
public/steam/isteamugc.h可实证(本机镜像已核对)。 SteamUGCDetails_t的具体字段(标题、订阅数、文件大小等):isteamugc.h明示。- 具体条目的线上数据(订阅量、评分、文件大小):创意工坊线上数据,以官方当前为准。
以上接口口径撰写时对照 Steamworks SDK v1.65 头文件与 partner.steamgames.com 官方文档核对;登录后可见数据以官方当前为准。
可运行产物:C++ 最小验证
下面的仿真复现「UGC 内容管道」的工程语义:查询句柄生命周期(创建、发送、读结果、越界、释放后失效)、订阅列表、下载状态位推进、安装信息与下载进度。它与 src/07-2-ugc-pipeline.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:
// file: src/07-2-ugc-pipeline.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/07-2-ugc-pipeline.cpp -o bin/07-2-ugc-pipeline && ./bin/07-2-ugc-pipeline
//
// mock:复现创意工坊 UGC 内容管道的接口语义——查询(CreateQueryAllUGCRequest /
// SendQueryUGCRequest / SteamUGCQueryCompleted_t)、结果读取与句柄释放、
// 订阅(SubscribeItem)、下载(DownloadItem)、安装状态(GetItemState)、
// 安装信息(GetItemInstallInfo)与下载进度(GetItemDownloadInfo)。
// 签名对照 SDK v1.65 isteamugc.h,非 Valve 实现。
#include "verify.h"
#include <cstdio>
#include <cstring>
#include <map>
#include <string>
#include <vector>
namespace steam_repro {
using MockAppId = uint32_t;
using MockPublishedFileId = uint64_t;
using MockQueryHandle = uint64_t;
// EItemState 位标志对照 isteamugc.h
enum MockItemState {
kStateNone = 0,
kStateSubscribed = 1,
kStateInstalled = 4,
kStateNeedsUpdate = 8,
kStateDownloading = 16,
kStateDownloadPending = 32,
};
// SteamUGCDetails_t 的简化视图(对照 isteamugc.h:SteamUGCDetails_t)
struct MockUgcDetails {
MockPublishedFileId publishedFileId = 0;
std::string title;
uint32_t subscriptions = 0;
int32_t fileSize = 0;
bool acceptedForUse = false;
};
struct MockCatalogItem {
MockUgcDetails details;
bool installed = false;
uint32_t state = kStateNone;
};
class MockSteamUGC {
public:
MockSteamUGC() : nextQuery_(1) {}
// ISteamUGC::CreateQueryAllUGCRequest:创建全量查询句柄(unPage 从 1 起)
MockQueryHandle createQueryAllUGCRequest(uint32_t page) {
if (page == 0) return kInvalidQuery;
MockQueryHandle h = nextQuery_++;
Query q;
q.page = page;
queries_[h] = q;
return h;
}
// ISteamUGC::SendQueryUGCRequest:发送查询(真实 SDK 经 SteamUGCQueryCompleted_t 回调)
// mock 中同步返回匹配结果数
uint32_t sendQueryUGCRequest(MockQueryHandle h) {
auto it = queries_.find(h);
if (it == queries_.end()) return 0;
uint32_t start = (it->second.page - 1) * kResultsPerPage;
uint32_t end = start + kResultsPerPage;
if (end > order_.size()) end = static_cast<uint32_t>(order_.size());
it->second.resultIds.clear();
for (uint32_t i = start; i < end; ++i) it->second.resultIds.push_back(order_[i]);
return it->second.resultIds.size();
}
// ISteamUGC::GetQueryUGCResult:读取单个查询结果
bool getQueryUGCResult(MockQueryHandle h, uint32_t index, MockUgcDetails* pDetails) {
auto it = queries_.find(h);
if (it == queries_.end() || index >= it->second.resultIds.size()) return false;
MockPublishedFileId fid = it->second.resultIds[index];
const MockCatalogItem& c = catalog_[fid];
*pDetails = c.details;
return true;
}
// ISteamUGC::ReleaseQueryUGCRequest:释放查询句柄
bool releaseQueryUGCRequest(MockQueryHandle h) {
auto it = queries_.find(h);
if (it == queries_.end()) return false;
queries_.erase(it);
return true;
}
// ISteamUGC::SubscribeItem:订阅条目(真实 SDK 异步经回调)
bool subscribeItem(MockPublishedFileId fid) {
auto it = catalog_.find(fid);
if (it == catalog_.end()) return false;
it->second.state |= kStateSubscribed;
bool dup = false;
for (MockPublishedFileId s : subscribed_) {
if (s == fid) dup = true;
}
if (!dup) subscribed_.push_back(fid);
return true;
}
// ISteamUGC::GetNumSubscribedItems / GetSubscribedItems
uint32_t getNumSubscribedItems() const { return static_cast<uint32_t>(subscribed_.size()); }
uint32_t getSubscribedItems(MockPublishedFileId* out, uint32_t maxEntries) const {
uint32_t n = 0;
for (MockPublishedFileId fid : subscribed_) {
if (n >= maxEntries) break;
out[n++] = fid;
}
return n;
}
// ISteamUGC::GetItemState:返回条目本机状态位
uint32_t getItemState(MockPublishedFileId fid) const {
auto it = catalog_.find(fid);
return it == catalog_.end() ? kStateNone : it->second.state;
}
// ISteamUGC::DownloadItem:发起下载(真实 SDK 返回 true 后等 DownloadItemResult_t)
bool downloadItem(MockPublishedFileId fid, bool highPriority) {
auto it = catalog_.find(fid);
if (it == catalog_.end()) return false;
it->second.state |= kStateDownloading;
it->second.state |= kStateDownloadPending;
return true;
}
// 模拟下载完成:DownloadItemResult_t 后条目可安装读取
void finishDownload(MockPublishedFileId fid) {
auto it = catalog_.find(fid);
if (it == catalog_.end()) return;
it->second.state &= ~static_cast<uint32_t>(kStateDownloading | kStateDownloadPending);
it->second.state |= kStateInstalled;
it->second.installed = true;
}
// ISteamUGC::GetItemInstallInfo:已安装条目的磁盘路径与大小
bool getItemInstallInfo(MockPublishedFileId fid, uint64_t* punSizeOnDisk, char* pchFolder,
uint32_t cchFolderSize, uint32_t* punTimeStamp) const {
auto it = catalog_.find(fid);
if (it == catalog_.end() || !it->second.installed) return false;
if (punSizeOnDisk) *punSizeOnDisk = static_cast<uint64_t>(it->second.details.fileSize);
if (pchFolder && cchFolderSize > 0)
std::snprintf(pchFolder, cchFolderSize, "workshop/content/%llu",
static_cast<unsigned long long>(fid));
if (punTimeStamp) *punTimeStamp = 1735000000;
return true;
}
// ISteamUGC::GetItemDownloadInfo:下载进度
bool getItemDownloadInfo(MockPublishedFileId fid, uint64_t* punBytesDownloaded,
uint64_t* punBytesTotal) const {
auto it = catalog_.find(fid);
if (it == catalog_.end()) return false;
const MockCatalogItem& c = it->second;
uint64_t total = static_cast<uint64_t>(c.details.fileSize);
uint64_t got = c.installed ? total : total / 2;
if (punBytesDownloaded) *punBytesDownloaded = got;
if (punBytesTotal) *punBytesTotal = total;
return true;
}
void addItem(MockPublishedFileId fid, const std::string& title, uint32_t subs, int32_t size,
bool accepted) {
MockCatalogItem c;
c.details.publishedFileId = fid;
c.details.title = title;
c.details.subscriptions = subs;
c.details.fileSize = size;
c.details.acceptedForUse = accepted;
catalog_[fid] = c;
order_.push_back(fid);
}
size_t catalogSize() const { return catalog_.size(); }
private:
static constexpr uint32_t kResultsPerPage = 50;
static constexpr MockQueryHandle kInvalidQuery = 0;
struct Query {
uint32_t page = 0;
std::vector<MockPublishedFileId> resultIds;
};
MockQueryHandle nextQuery_;
std::map<MockQueryHandle, Query> queries_;
std::map<MockPublishedFileId, MockCatalogItem> catalog_;
std::vector<MockPublishedFileId> order_;
std::vector<MockPublishedFileId> subscribed_;
};
} // namespace steam_repro
int main() {
using namespace steam_repro;
MockSteamUGC ugc;
ugc.addItem(1001, "简易小屋蓝图", 12000, 2048, true);
ugc.addItem(1002, "城市地标合集", 8600, 4096, true);
ugc.addItem(1003, "隧道夜景包", 2100, 1536, true);
// 1. 创建查询句柄(page=0 返回无效句柄)
MockQueryHandle q = ugc.createQueryAllUGCRequest(1);
CHECK(q != 0);
CHECK(ugc.createQueryAllUGCRequest(0) == 0);
// 2. 发送查询:返回结果数(SteamUGCQueryCompleted_t::m_unNumResultsReturned 语义)
CHECK(ugc.sendQueryUGCRequest(q) == 3);
// 3. 读取查询结果:标题与订阅数
MockUgcDetails d;
CHECK(ugc.getQueryUGCResult(q, 0, &d));
CHECK(d.publishedFileId == 1001);
CHECK(d.title == "简易小屋蓝图");
CHECK(d.subscriptions == 12000);
// 4. 越界索引读取失败
CHECK(!ugc.getQueryUGCResult(q, 99, &d));
// 5. 释放查询句柄后不可再用
CHECK(ugc.releaseQueryUGCRequest(q));
CHECK(!ugc.getQueryUGCResult(q, 0, &d));
// 6. 订阅前:状态为 None;订阅后:Subscribed 位
CHECK(ugc.getItemState(1002) == kStateNone);
CHECK(ugc.subscribeItem(1002));
CHECK(ugc.getItemState(1002) == kStateSubscribed);
CHECK(ugc.getNumSubscribedItems() == 1);
// 7. 订阅列表读取
MockPublishedFileId ids[8];
CHECK(ugc.getSubscribedItems(ids, 8) == 1);
CHECK(ids[0] == 1002);
// 8. DownloadItem:进入 Downloading|DownloadPending
CHECK(ugc.downloadItem(1002, false));
CHECK(ugc.getItemState(1002) == (kStateSubscribed | kStateDownloading | kStateDownloadPending));
// 9. 下载完成前:GetItemInstallInfo 返回 false,进度半程
char folder[128];
uint64_t got = 0, tot = 0;
CHECK(!ugc.getItemInstallInfo(1002, &got, folder, sizeof(folder), nullptr));
CHECK(ugc.getItemDownloadInfo(1002, &got, &tot));
CHECK(got == tot / 2);
// 10. 下载完成:Installed 位生效,安装信息可读
ugc.finishDownload(1002);
CHECK(ugc.getItemState(1002) == (kStateSubscribed | kStateInstalled));
CHECK(ugc.getItemInstallInfo(1002, &got, folder, sizeof(folder), nullptr));
CHECK(got == 4096);
CHECK(std::string(folder).find("workshop/content") != std::string::npos);
return lab::report("07-2 UGC 内容管道");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 25/25 通过。
小结
- 查询是「创建句柄 → 发送(异步回调)→ 按索引读结果 → 释放」的生命周期,句柄要用 RAII 管理。
SubscribeItem建立订阅关系,DownloadItem触发内容落地,都经异步回调确认。- 内容可用判断看
GetItemState的Installed位;订阅列表不等于已安装列表。 - 下载进度与安装信息都要先判返回值/判空,未安装时
GetItemInstallInfo返回 false。
阅读导航:上一节:7.1 创意工坊机制 · 下一节:7.3 创意工坊商业 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。