《Steam 游戏平台:开发与商业化》7.1 创意工坊机制

创意工坊条目的生命周期是「创建 → 更新 → 提交」三步:CreateItem 拿版本号、StartItemUpdate 开一次更新、SubmitItemUpdate 上传并进入 EItemUpdateStatus 状态机。消费者侧由 EItemState 位标志描述订阅与安装。本节讲创意工坊机制接口语义,lab 用 C++ mock 复现条目生命周期与状态迁移。

7.1 创意工坊机制

上一节讲完 DLC,这一节进入第二个内容通道:创意工坊。DLC 是开发者生产、商店分发的内容;创意工坊是玩家生产、社区分发的内容。条目(Item)的生命周期是「创建 → 更新 → 提交」三步:CreateItem 拿到 PublishFileID,StartItemUpdate 开一次更新,SubmitItemUpdate 把变更上传并进入 EItemUpdateStatus 状态机。消费者侧用 EItemState 位标志描述订阅与安装。

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

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

  • Steam 发行专题 (操作手册)讲「后台开创意工坊、配 UGC 规则」;本节讲「代码里创建与更新条目的接口语义」。
  • 卷一讲平台机制;本节讲条目生命周期与状态机——CreateItem/StartItemUpdate/SubmitItemUpdate 的三步流程与 EItemUpdateStatus 迁移。
  • lab 用纯 C++ 复现条目创建、字段设置、提交与状态迁移,不依赖 Steam 客户端运行。

三步生命周期:创建、更新、提交

创意工坊条目的创建与更新不是「写个文件就完事」,而是三步异步流程。v1.65 的 Creator API:

// isteamugc.h:CreateItem / StartItemUpdate / SubmitItemUpdate / SetItemTitle(SDK v1.65 头文件摘录,已删减)
STEAM_CALL_RESULT( CreateItemResult_t )
virtual SteamAPICall_t CreateItem( AppId_t nConsumerAppId, EWorkshopFileType eFileType ) = 0; // create new item for this app with no content attached yet

virtual UGCUpdateHandle_t StartItemUpdate( AppId_t nConsumerAppId, PublishedFileId_t nPublishedFileID ) = 0; // start an UGC item update. Set changed properties before commiting update with CommitItemUpdate()

virtual bool SetItemTitle( UGCUpdateHandle_t handle, const char *pchTitle ) = 0; // change the title of an UGC item
virtual bool SetItemDescription( UGCUpdateHandle_t handle, const char *pchDescription ) = 0; // change the description of an UGC item
virtual bool SetItemContent( UGCUpdateHandle_t handle, const char *pszContentFolder ) = 0; // update item content from this local folder

STEAM_CALL_RESULT( SubmitItemUpdateResult_t )
virtual SteamAPICall_t SubmitItemUpdate( UGCUpdateHandle_t handle, const char *pchChangeNote ) = 0; // commit update process started with StartItemUpdate()

工程语义:

  1. CreateItem 是异步的:返回 SteamAPICall_t,真正的 PublishFileID 在 CreateItemResult_t 回调里(m_nPublishedFileId)。回调里还带 m_bUserNeedsToAcceptWorkshopLegalAgreement——玩家可能要先接受创意工坊协议。
  2. StartItemUpdate 是「改一次」的句柄:对已有条目开一次更新,之后所有 SetItemTitle/SetItemDescription/SetItemContent 都往这个句柄上写。字段设置是同步返回 bool 的,但提交是异步的。
  3. 提交只传变更说明:SubmitItemUpdate 的 pchChangeNote 是给玩家看的更新日志。提交的字节内容来自 SetItemContent 指定的本地目录,SDK 会计算增量上传。

上传状态机:EItemUpdateStatus

提交之后,上传进入可观测的状态机。v1.65 的枚举与进度查询:

// isteamugc.h:EItemUpdateStatus / GetItemUpdateProgress(SDK v1.65 头文件摘录,已删减)
enum EItemUpdateStatus
{
	k_EItemUpdateStatusInvalid 				= 0, // The item update handle was invalid, job might be finished, listen too SubmitItemUpdateResult_t
	k_EItemUpdateStatusPreparingConfig 		= 1, // The item update is processing configuration data
	k_EItemUpdateStatusPreparingContent		= 2, // The item update is reading and processing content files
	k_EItemUpdateStatusUploadingContent		= 3, // The item update is uploading content changes to Steam
	k_EItemUpdateStatusUploadingPreviewFile	= 4, // The item update is uploading new preview file image
	k_EItemUpdateStatusCommittingChanges	= 5  // The item update is committing all changes
};
virtual EItemUpdateStatus GetItemUpdateProgress( UGCUpdateHandle_t handle, uint64 *punBytesProcessed, uint64* punBytesTotal ) = 0;

工程语义:

  1. 状态迁移由 SDK 后台驱动:PreparingConfig → PreparingContent → UploadingContent → UploadingPreviewFile → CommittingChanges。接入工程用 GetItemUpdateProgress 轮询展示进度,但提交完成的真相在 SubmitItemUpdateResult_t 回调——不要用状态值当完成信号。
  2. k_EItemUpdateStatusInvalid 可能是「已完成」:头文件注释点名——「job might be finished」。句柄失效不等于失败,要等结果回调区分。
  3. punBytesTotal 可能是 0:上传尚未开始传输时总字节未知,做进度条前先判空(与 6.2 的下载进度同一条惯例)。

消费者状态位:EItemState

玩家侧用 GetItemState 读取条目的本地状态,返回值是位标志组合。v1.65 枚举:

// isteamugc.h:EItemState(SDK v1.65 头文件摘录,已删减)
enum EItemState
{
	k_EItemStateNone			= 0,	// item not tracked on client
	k_EItemStateSubscribed		= 1,	// current user is subscribed to this item. Not just cached.
	k_EItemStateLegacyItem		= 2,	// item was created with ISteamRemoteStorage
	k_EItemStateInstalled		= 4,	// item is installed and usable (but maybe out of date)
	k_EItemStateNeedsUpdate		= 8,	// items needs an update. Either because it's not installed yet or creator updated content
	k_EItemStateDownloading		= 16,	// item update is currently downloading
	k_EItemStateDownloadPending	= 32,	// DownloadItem() was called for this item, content isn't available until DownloadItemResult_t is fired
	k_EItemStateDisabledLocally = 64,	// Item is disabled locally, so it shouldn't be considered subscribed
};

工程语义:

  1. 状态是位标志,不是枚举值:k_EItemStateSubscribed | k_EItemStateInstalled 表示「已订阅且已安装」。判断「内容可用」要检查 Installed 位,而不是做相等比较。
  2. 「已订阅但未安装」与「已安装但可更新」要区分:NeedsUpdate 位表示创作者发布了新版本;此时内容「可用但是旧版」。加载条目的逻辑必须能处理「旧版可用 + 新版在后台更新」的窗口。
  3. DisabledLocally 是本地决策:玩家手动禁用的条目不应再出现在加载列表,但订阅关系还在。接入工程要在「订阅列表」和「实际加载列表」之间加一层过滤。

接口签名对照

头文件条目语义
isteamugc.hISteamUGC::CreateItem异步创建条目(回调给出版本号)
isteamugc.hISteamUGC::StartItemUpdate开启一次条目更新
isteamugc.hISteamUGC::SetItemTitle/SetItemDescription/SetItemContent更新字段与本地内容目录
isteamugc.hISteamUGC::SubmitItemUpdate提交更新(异步,带变更说明)
isteamugc.hISteamUGC::GetItemUpdateProgress上传进度(EItemUpdateStatus + 字节对)
isteamugc.hEItemUpdateStatus上传状态机枚举
isteamugc.hEItemState条目本地状态位(订阅/安装/待更新…)
isteamugc.hISteamUGC::GetItemState读取条目状态位

数据口径与来源

  • 接口签名、枚举值、位标志含义:SDK v1.65 public/steam/isteamugc.h 可实证(本机镜像已核对)。
  • CreateItemResult_t/SubmitItemUpdateResult_t 回调字段:isteamugc.h 明示。
  • 具体条目的标题、订阅量、文件大小:创意工坊线上数据,以官方当前为准。

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

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

下面的仿真复现「创意工坊机制」的工程语义:条目创建、更新字段设置、提交、EItemUpdateStatus 上传状态机迁移、EItemState 消费者状态位翻转。它与 src/07-1-workshop-mechanics.cpp 逐字节一致,mock 签名对照 SDK v1.65 头文件:

// file: src/07-1-workshop-mechanics.cpp
// tier: L1
// verify: clang++ -std=c++20 -Wall -I. src/07-1-workshop-mechanics.cpp -o bin/07-1-workshop-mechanics && ./bin/07-1-workshop-mechanics
//
// mock:复现 ISteamUGC 的创意工坊条目生命周期——CreateItem → StartItemUpdate →
// 设置字段 → SubmitItemUpdate → GetItemUpdateProgress 更新状态机;
// EItemUpdateStatus 状态迁移与 EItemState 消费者状态位。
// 签名对照 SDK v1.65 isteamugc.h,非 Valve 实现。
#include "verify.h"

#include <map>
#include <string>

namespace steam_repro {

using MockAppId = uint32_t;
using MockPublishedFileId = uint64_t;
using MockUpdateHandle = uint64_t;

// EItemUpdateStatus 枚举值对照 isteamugc.h
enum MockItemUpdateStatus {
  kInvalid = 0,
  kPreparingConfig = 1,
  kPreparingContent = 2,
  kUploadingContent = 3,
  kUploadingPreviewFile = 4,
  kCommittingChanges = 5,
};

// EItemState 位标志对照 isteamugc.h
enum MockItemState {
  kStateNone = 0,
  kStateSubscribed = 1,
  kStateInstalled = 4,
  kStateNeedsUpdate = 8,
  kStateDownloading = 16,
};

struct MockItem {
  MockAppId consumerApp = 0;
  int fileType = 0;
  uint32_t state = kStateNone;
  std::string title;
  std::string description;
  std::string contentFolder;
};

struct MockUpdate {
  MockPublishedFileId fileId = 0;
  uint64_t bytesProcessed = 0;
  uint64_t bytesTotal = 0;
  bool submitted = false;
  MockItemUpdateStatus status = kPreparingConfig;
  std::string changeNote;
  std::string title;
  std::string description;
  std::string contentFolder;
};

class MockSteamUGC {
 public:
  MockSteamUGC() : nextPublished_(1001), nextUpdate_(1) {}

  // ISteamUGC::CreateItem:创建新条目(真实 SDK 异步经 CreateItemResult_t 给出版本号)
  // 对照 isteamugc.h:CreateItem
  MockPublishedFileId createItem(MockAppId consumerApp, int fileType) {
    MockPublishedFileId id = nextPublished_++;
    MockItem it;
    it.consumerApp = consumerApp;
    it.fileType = fileType;
    items_[id] = it;
    return id;
  }

  // ISteamUGC::StartItemUpdate:为已有条目开启一次更新
  MockUpdateHandle startItemUpdate(MockAppId consumerApp, MockPublishedFileId fileId) {
    if (items_.find(fileId) == items_.end()) return kInvalidUpdate;
    MockUpdateHandle h = nextUpdate_++;
    MockUpdate u;
    u.fileId = fileId;
    u.bytesTotal = 1024 * 1024;
    updates_[h] = u;
    return h;
  }

  // ISteamUGC::SetItemTitle / SetItemDescription / SetItemContent
  bool setItemTitle(MockUpdateHandle h, const std::string& title) {
    MockUpdate* u = findUpdate(h);
    if (!u) return false;
    u->title = title;
    return true;
  }
  bool setItemDescription(MockUpdateHandle h, const std::string& desc) {
    MockUpdate* u = findUpdate(h);
    if (!u) return false;
    u->description = desc;
    return true;
  }
  bool setItemContent(MockUpdateHandle h, const std::string& folder) {
    MockUpdate* u = findUpdate(h);
    if (!u) return false;
    u->contentFolder = folder;
    return true;
  }

  // ISteamUGC::SubmitItemUpdate:提交更新(真实 SDK 异步经 SubmitItemUpdateResult_t 回调)
  bool submitItemUpdate(MockUpdateHandle h, const std::string& changeNote) {
    MockUpdate* u = findUpdate(h);
    if (!u) return false;
    u->submitted = true;
    u->status = kPreparingContent;
    u->bytesProcessed = 0;
    u->changeNote = changeNote;
    return true;
  }

  // ISteamUGC::GetItemUpdateProgress:返回当前上传状态与字节进度(无副作用)
  MockItemUpdateStatus getItemUpdateProgress(MockUpdateHandle h, uint64_t* bytesProcessed,
                                             uint64_t* bytesTotal) const {
    const MockUpdate* u = findUpdate(h);
    if (!u) return kInvalid;
    if (bytesProcessed) *bytesProcessed = u->bytesProcessed;
    if (bytesTotal) *bytesTotal = u->bytesTotal;
    return u->status;
  }

  // 模拟异步上传在后台推进(真实 SDK 由 Steam 后台驱动上传线程推进)
  MockItemUpdateStatus pumpUpload(MockUpdateHandle h) {
    MockUpdate* u = findUpdate(h);
    if (!u) return kInvalid;
    if (u->status == kPreparingConfig) {
      u->status = kPreparingContent;
    } else if (u->status == kPreparingContent) {
      u->status = kUploadingContent;
      u->bytesProcessed = u->bytesTotal / 2;
    } else if (u->status == kUploadingContent) {
      u->status = kCommittingChanges;
      u->bytesProcessed = u->bytesTotal;
    } else if (u->status == kCommittingChanges) {
      u->status = kInvalid;  // 完成后句柄失效
    }
    return u->status;
  }

  // ISteamUGC::GetItemState:返回条目在本机的状态位
  uint32_t getItemState(MockPublishedFileId fileId) const {
    auto it = items_.find(fileId);
    return it == items_.end() ? kStateNone : it->second.state;
  }

  // 模拟消费者侧:订阅并安装(DownloadItem 完成后的状态迁移)
  void subscribeAndInstall(MockPublishedFileId fileId) {
    auto it = items_.find(fileId);
    if (it == items_.end()) return;
    it->second.state = kStateSubscribed | kStateInstalled;
  }

  // 模拟创作者发布新版本:已安装条目进入 NeedsUpdate
  void publishNewVersion(MockPublishedFileId fileId) {
    auto it = items_.find(fileId);
    if (it == items_.end()) return;
    it->second.state = kStateSubscribed | kStateNeedsUpdate;
  }

  bool commitUpdateToItem(MockUpdateHandle h) {
    MockUpdate* u = findUpdate(h);
    if (!u || u->status != kInvalid) return false;
    MockItem& item = items_[u->fileId];
    if (!u->title.empty()) item.title = u->title;
    if (!u->description.empty()) item.description = u->description;
    if (!u->contentFolder.empty()) item.contentFolder = u->contentFolder;
    return true;
  }

  const MockItem* item(MockPublishedFileId fileId) const {
    auto it = items_.find(fileId);
    return it == items_.end() ? nullptr : &it->second;
  }

 private:
  MockUpdate* findUpdate(MockUpdateHandle h) {
    auto it = updates_.find(h);
    return it == updates_.end() ? nullptr : &it->second;
  }
  const MockUpdate* findUpdate(MockUpdateHandle h) const {
    auto it = updates_.find(h);
    return it == updates_.end() ? nullptr : &it->second;
  }

  static constexpr MockUpdateHandle kInvalidUpdate = 0;
  MockPublishedFileId nextPublished_;
  MockUpdateHandle nextUpdate_;
  std::map<MockPublishedFileId, MockItem> items_;
  std::map<MockUpdateHandle, MockUpdate> updates_;
};

}  // namespace steam_repro

int main() {
  using namespace steam_repro;
  MockSteamUGC ugc;

  // 1. CreateItem:创建条目并分配 PublishFileID
  MockPublishedFileId fid = ugc.createItem(480, 0);
  CHECK(fid == 1001);

  // 2. 新条目初始状态为 kStateNone
  CHECK(ugc.getItemState(fid) == kStateNone);

  // 3. StartItemUpdate:对不存在的条目返回无效句柄
  MockUpdateHandle bad = ugc.startItemUpdate(480, 99999);
  CHECK(bad == 0);
  MockUpdateHandle h = ugc.startItemUpdate(480, fid);
  CHECK(h != 0);

  // 4. 设置字段:标题/描述/内容目录
  CHECK(ugc.setItemTitle(h, "碳基沙盒蓝图"));
  CHECK(ugc.setItemDescription(h, "一套可订阅的蓝图包"));
  CHECK(ugc.setItemContent(h, "content/blueprint-pack"));

  // 5. 提交前 GetItemUpdateProgress 处于 PreparingConfig
  uint64_t proc = 0, total = 0;
  CHECK(ugc.getItemUpdateProgress(h, &proc, &total) == kPreparingConfig);

  // 6. SubmitItemUpdate:进入 PreparingContent
  CHECK(ugc.submitItemUpdate(h, "首版发布"));
  CHECK(ugc.getItemUpdateProgress(h, &proc, &total) == kPreparingContent);

  // 7. 上传推进:UploadingContent 半程
  CHECK(ugc.pumpUpload(h) == kUploadingContent);
  CHECK(ugc.getItemUpdateProgress(h, &proc, &total) == kUploadingContent);
  CHECK(proc == total / 2);

  // 8. 提交推进:CommittingChanges 满程
  CHECK(ugc.pumpUpload(h) == kCommittingChanges);
  CHECK(ugc.getItemUpdateProgress(h, &proc, &total) == kCommittingChanges);
  CHECK(proc == total);

  // 9. 完成后句柄失效(返回 Invalid)
  CHECK(ugc.pumpUpload(h) == kInvalid);

  // 10. 提交内容落回条目
  CHECK(ugc.commitUpdateToItem(h));
  CHECK(ugc.item(fid)->title == "碳基沙盒蓝图");
  CHECK(ugc.item(fid)->contentFolder == "content/blueprint-pack");

  // 11. 消费者侧状态位:订阅+安装、创作者更新后进入 NeedsUpdate
  ugc.subscribeAndInstall(fid);
  CHECK(ugc.getItemState(fid) == (kStateSubscribed | kStateInstalled));
  ugc.publishNewVersion(fid);
  CHECK(ugc.getItemState(fid) == (kStateSubscribed | kStateNeedsUpdate));

  return lab::report("07-1 创意工坊机制");
}

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

小结

  • 条目生命周期三步:CreateItem(异步拿版本号)→ StartItemUpdate(改字段)→ SubmitItemUpdate(异步提交)。
  • EItemUpdateStatus 是上传状态机,但完成信号在 SubmitItemUpdateResult_t 回调;Invalid 可能是「已完成」。
  • EItemState 是位标志:判断「内容可用」检查 Installed 位,「可更新」检查 NeedsUpdate 位。
  • DisabledLocally 在订阅列表与加载列表之间加一层过滤。

阅读导航:上一节:6.3 DLC 商业策略 · 下一节:7.2 UGC 内容管道 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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