上传、订阅与加载

Steam 创意工坊实现：上传、订阅与加载

使用 Steamworks 的 ISteamUGC 接口，可以为游戏接入创意工坊内容。本页按上传和消费两条路径解释关键调用，适合已经准备好 Steamworks 应用及自有内容格式的开发者；调用签名和回调字段应以项目使用的 SDK 头文件及官方参考为准。

创意工坊内容从创作者到游戏客户端的传递流程

配置应用

在 Steamworks 应用管理中配置 Steam Cloud 的每用户字节配额和文件数量配额，供工坊预览图存储使用。在 Workshop 配置的 Additional Configuration Options 中启用 Enable ISteamUGC for file transfer。保存并通过 Publish 流程发布更改后，才能按官方指南上传内容。如果使用独立上传工具，还需在游戏的 Workshop 配置中的 App Publish Permissions 添加该工具的 App ID，并为游戏和工具两个应用都设置 Steam Cloud 配额、发布配置。应用通过 SteamUGC() 获得接口；游戏仍应完成 Steamworks 初始化及回调处理。

创建与更新项目

  1. 调用 CreateItem，传入消费内容的游戏 App ID。若上传器是独立应用，不要误传工具自身的 App ID。即用型 Mod 一般使用 k_EWorkshopFileTypeCommunity；供开发者精选的提交使用 k_EWorkshopFileTypeMicrotransaction。
  2. 注册并处理 CreateItemResult_t。先检查 m_eResult，成功后保存 m_nPublishedFileId，后续更新需要该 ID；同时检查是否要求用户接受工坊协议。
  3. 用该 ID 调用 StartItemUpdate，再通过对应 SetItem... 方法设置标题、说明、标签、可见性、预览图和内容目录。SetItemContent 接收的是项目文件夹；按需使用 SetItemMetadata 保存查询时可取回的元数据。
  4. 调用 SubmitItemUpdate，等待 SubmitItemUpdateResult_t 并检查结果。可用 GetItemUpdateProgress 查询阶段和字节数；总字节数可能随阶段变化。提交后没有取消此次上传的方法。

创建或更新回调提示需要接受协议时，应引导创作者完成确认。官方还建议在提交按钮附近提供协议链接，并在提交后通过 ISteamFriends::ActivateGameOverlayToWebPage 打开 steam://url/CommunityFilePage/<项目ID>，方便创作者检查项目和确认协议。未接受协议的项目默认隐藏。

枚举订阅与等待安装

使用 GetNumSubscribedItems 和 GetSubscribedItems 获取当前用户订阅的项目；也可用 SubscribeItem、UnsubscribeItem 在游戏中管理订阅。外部订阅变化可通过 RemoteStoragePublishedFileSubscribed_t 和 RemoteStoragePublishedFileUnsubscribed_t 监听，回调涉及所有应用，因此应核对应用 ID。

使用 GetItemState 检查安装和更新状态。新订阅的项目可能在游戏启动后仍在后台下载，不能因为项目已订阅就假设文件已经可读。监听 ItemInstalled_t；对于已安装且无需更新的项目，调用 GetItemInstallInfo 并检查其布尔返回值，再由游戏验证并加载。ISteamUGC 项目返回内容目录；带有 k_EItemStateLegacyItem 的旧版项目返回的可能是文件路径，加载器应区分处理。

需要主动下载或更新时，可调用 DownloadItem。若调用返回 true，等待 DownloadItemResult_t，核对应用 ID 和结果，再读取安装信息或访问磁盘。对未订阅项目的下载可能只是临时缓存。游戏还应处理下载失败、内容缺失、文件格式错误及运行中更新等情况。

查询与服务器

通过 CreateQueryUserUGCRequest、CreateQueryAllUGCRequest 或 CreateQueryUGCDetailsRequest 创建适合场景的查询，设置标签或搜索条件后调用 SendQueryUGCRequest。在 SteamUGCQueryCompleted_t 回调中检查结果并读取条目，最后调用 ReleaseQueryUGCRequest 释放查询资源。官方指南中的列表分页查询每页最多返回 50 条，页码从 1 开始；按 ID 查询详情的限制请参阅对应 API。

专用服务器可由运营者或客户端提供项目 ID，再使用 DownloadItem 获取临时副本，等待结果并通过 GetItemInstallInfo 定位内容。服务器应自行验证客户端提供的 ID 和文件，避免把外部内容直接视为可信游戏数据。

排查与测试

下载和安装问题可查看 Steam/logs/Workshop_log.txt；上传与更新可查看 Steam/workshopbuilds/depot_build_<appid>.log，并记录回调中的 EResult。Steamworks SDK 的 SpaceWar 示例展示了部分加载与安装回调流程。官方允许用 SteamCMD 的 workshop_build_item 辅助测试，但因涉及 Steam 登录凭据，不应把它作为要求普通玩家输入凭据的正式上传方案。

参考 Steam 创意工坊实现指南 和 ISteamUGC 接口。