《Steam 游戏平台:开发与商业化》7.2 UGC 内容管道

创意工坊的消费侧是查询、订阅、下载三段管道:CreateQueryAllUGCRequest/SendQueryUGCRequest 拿查询结果、SubscribeItem 订阅、DownloadItem 触发下载、GetItemInstallInfo/GetItemDownloadInfo 读安装与进度。本节讲 UGC 内容管道的接口语义,lab 用 C++ mock 复现查询句柄生命周期与订阅下载状态迁移。

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;

工程语义:

  1. 查询句柄是显式资源:创建到释放是完整生命周期。ReleaseQueryUGCRequest 之后句柄不可再用,接入工程要用 RAII 包装句柄,防止查询泄漏。
  2. SendQueryUGCRequest 是异步的:返回 SteamAPICall_t,结果经 SteamUGCQueryCompleted_t 回调到达(回调里的 m_unNumResultsReturned 是本次返回的条数)。mock 里为了可验证做了同步返回,但接入工程必须按回调驱动。
  3. 结果是「游标 + 按索引读」: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;

工程语义:

  1. SubscribeItem 不是「立即下载」:头文件注释「will be installed ASAP」。订阅建立关系,内容落地由 SDK 排队处理;DownloadItem(..., bHighPriority) 可提高优先级。两者都经异步回调(DownloadItemResult_t)确认结果。
  2. 「已订阅」与「已安装」用状态位分开:GetItemState 返回位标志。判断内容可用要检查 Installed 位;订阅列表(GetSubscribedItems)不等于已安装列表。
  3. 安装信息带显式目录:GetItemInstallInfo 输出磁盘路径与大小。注意 punSizeOnDisk 的目录是内容在创意工坊下载目录下的相对路径,读取条目前要检查该接口的返回值——未安装时返回 false。
  4. 下载进度对是「已下 / 总量」:GetItemDownloadInfo 输出字节对。总量可能为 0(尚未开始传输),做百分比前先判空,与 6.2 的 DLC 下载进度同一惯例。

状态迁移的完整窗口

一个条目从订阅到可用,状态位依次出现:Subscribed → Subscribed|Downloading|DownloadPending → Subscribed|Installed。如果创作者发布新版本,还会叠加 NeedsUpdate。接入工程要注意三个时间窗:

  1. 订阅但未下载:条目在订阅列表里,但 GetItemState 没有 Installed 位,GetItemInstallInfo 返回 false。此时创意工坊菜单显示「下载中/未安装」,不加载内容。
  2. 下载进行中:Downloading|DownloadPending 位存在,进度对持续更新。此时玩家可能切去别的地方,回来时内容可用。
  3. 已安装但可更新:Installed 位存在,但叠加 NeedsUpdate。游戏应继续用旧版内容,同时后台推进更新,而不是中断玩家。

接口签名对照

头文件条目语义
isteamugc.hISteamUGC::CreateQueryAllUGCRequest创建全量查询句柄(分页从 1 起)
isteamugc.hISteamUGC::SendQueryUGCRequest发送查询(异步,经 SteamUGCQueryCompleted_t 回调)
isteamugc.hISteamUGC::GetQueryUGCResult按索引读查询结果(SteamUGCDetails_t)
isteamugc.hISteamUGC::ReleaseQueryUGCRequest释放查询句柄
isteamugc.hISteamUGC::SubscribeItem订阅条目(异步)
isteamugc.hISteamUGC::GetNumSubscribedItems/GetSubscribedItems订阅列表读取
isteamugc.hISteamUGC::DownloadItem触发内容下载(可加急)
isteamugc.hISteamUGC::GetItemInstallInfo已安装条目的磁盘路径与大小
isteamugc.hISteamUGC::GetItemDownloadInfo下载进度(已下/总量)
isteamugc.hISteamUGC::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 创意工坊商业 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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