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()
工程语义:
CreateItem是异步的:返回SteamAPICall_t,真正的 PublishFileID 在CreateItemResult_t回调里(m_nPublishedFileId)。回调里还带m_bUserNeedsToAcceptWorkshopLegalAgreement——玩家可能要先接受创意工坊协议。StartItemUpdate是「改一次」的句柄:对已有条目开一次更新,之后所有SetItemTitle/SetItemDescription/SetItemContent都往这个句柄上写。字段设置是同步返回 bool 的,但提交是异步的。- 提交只传变更说明:
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;
工程语义:
- 状态迁移由 SDK 后台驱动:
PreparingConfig → PreparingContent → UploadingContent → UploadingPreviewFile → CommittingChanges。接入工程用GetItemUpdateProgress轮询展示进度,但提交完成的真相在SubmitItemUpdateResult_t回调——不要用状态值当完成信号。 k_EItemUpdateStatusInvalid可能是「已完成」:头文件注释点名——「job might be finished」。句柄失效不等于失败,要等结果回调区分。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
};
工程语义:
- 状态是位标志,不是枚举值:
k_EItemStateSubscribed | k_EItemStateInstalled表示「已订阅且已安装」。判断「内容可用」要检查Installed位,而不是做相等比较。 - 「已订阅但未安装」与「已安装但可更新」要区分:
NeedsUpdate位表示创作者发布了新版本;此时内容「可用但是旧版」。加载条目的逻辑必须能处理「旧版可用 + 新版在后台更新」的窗口。 DisabledLocally是本地决策:玩家手动禁用的条目不应再出现在加载列表,但订阅关系还在。接入工程要在「订阅列表」和「实际加载列表」之间加一层过滤。
接口签名对照
| 头文件 | 条目 | 语义 |
|---|---|---|
isteamugc.h | ISteamUGC::CreateItem | 异步创建条目(回调给出版本号) |
isteamugc.h | ISteamUGC::StartItemUpdate | 开启一次条目更新 |
isteamugc.h | ISteamUGC::SetItemTitle/SetItemDescription/SetItemContent | 更新字段与本地内容目录 |
isteamugc.h | ISteamUGC::SubmitItemUpdate | 提交更新(异步,带变更说明) |
isteamugc.h | ISteamUGC::GetItemUpdateProgress | 上传进度(EItemUpdateStatus + 字节对) |
isteamugc.h | EItemUpdateStatus | 上传状态机枚举 |
isteamugc.h | EItemState | 条目本地状态位(订阅/安装/待更新…) |
isteamugc.h | ISteamUGC::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 内容管道 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。