ISteamUGC:发布、更新与依赖

ISteamUGC 发布接口:创建、更新和依赖管理

Steam 创意工坊的 ISteamUGC 发布接口将项目创建、内容更新和依赖维护拆成多个操作。本页面向游戏及上传工具开发者,列出各调用的输入、结果与使用限制,帮助定位具体接口;完整声明应以所用 Steamworks SDK 头文件为准。

创作者向 Steam 工坊提交内容并由玩家或服务器加载的流程

创建、提交和删除

通过 SteamUGC() 访问接口。创建和更新均为异步流程,要持续运行 Steam 回调并检查返回结果。

  • CreateItem:传消费内容的游戏 App ID 与 EWorkshopFileType,创建一个尚无内容的项目;返回 SteamAPICall_t,在 CreateItemResult_t 中读取结果、项目 ID 和是否需要接受协议。
  • StartItemUpdate:传消费应用 ID 和已发布项目 ID,取得更新句柄;无效句柄应作为失败处理。
  • SubmitItemUpdate:传更新句柄和更新说明,返回异步调用句柄;以 SubmitItemUpdateResult_t 确认结果与协议状态。提交后不能取消该上传。
  • GetItemUpdateProgress:传更新句柄和两个字节数输出参数,返回 EItemUpdateStatus;总数可能随处理阶段变化,不能仅凭进度判断提交成功。
  • DeleteItem:传项目 ID,异步返回 DeleteItemResult_t;调用不自动提示且删除不可撤销,工具应让用户明确确认目标。

设置项目内容

以下设置均针对 StartItemUpdate 返回的更新句柄,须在提交之前调用。它们返回 bool,应逐项检查;成功设置不代表最终上传成功。

  • SetItemContent:传内容文件夹的本地绝对路径。官方建议不要为传输把所有文件合并压缩成一个文件,以利于高效更新。
  • SetItemPreview:传主要预览图片绝对路径;预览保存在用户云中,应用必须配置 Steam 云配额及文件数。
  • SetItemTitle 和 SetItemDescription:分别设置标题和描述,长度受对应 k_cchPublishedDocument...Max 限制。
  • SetItemUpdateLanguage:设置此次标题和描述的 API 语言代码,默认 english。
  • SetItemVisibility:传 ERemoteStoragePublishedFileVisibility 设置项目可见性。
  • SetItemTags:传字符串数组;每个标签最多 255 字符,使用可打印字符且不能包含逗号。
  • SetItemMetadata:设置可查询的开发者元数据,大小受 k_cchDeveloperMetadataMax 限制;查询时配合 SetReturnMetadata。
  • SetRequiredGameVersions:传最小和最大 Steam 测试分支名,空字符串表示范围向该端延伸;官方说明仅当实际内容发生变化时应用。

键值标签、额外预览与描述词

  • AddItemKeyValueTag:传更新句柄及键和值;键只能含字母数字和下划线,键和值各不超过 255 字符,一个键可对应多个值,搜索采用精确匹配。单次更新添加超过 100 项会失败。
  • RemoveItemKeyValueTags:按键移除现有键值标签;单次更新最多调用 100 次。
  • AddItemPreviewFile:传本地图片绝对路径和 EItemPreviewType;图片需小于 1 MB,支持网页可显示的格式;YouTube 视频应使用专用函数。
  • AddItemPreviewVideo:传 YouTube 视频 ID 添加额外预览。
  • UpdateItemPreviewFile、UpdateItemPreviewVideo:传更新句柄、已有预览索引以及替换文件路径或视频 ID。
  • RemoveItemPreview:传更新句柄和预览索引,移除额外预览。官方页面对其参数及返回说明较少,应以 SDK 头文件和实际结果为准。
  • AddContentDescriptor 与 RemoveContentDescriptor:传更新句柄和内容描述词枚举,设置或移除标记;返回 bool。描述词由 Steam 用于内容筛选。

项目与应用依赖

  • AddDependency 和 RemoveDependency:传父项目与子项目 ID,异步返回对应的 UGC 依赖结果。父项为合集时添加的子项成为合集成员;普通项目的依赖是软依赖,游戏需自行处理。
  • AddAppDependency 和 RemoveAppDependency:传项目 ID 与应用或 DLC App ID,结果分别由对应回调提供;应用依赖是网页展示的软依赖。
  • GetAppDependencies:按项目 ID 获取应用依赖,处理 GetAppDependenciesResult_t。官方页面对声明与返回类型有不一致之处,以 SDK 为准。

参考:ISteamUGC 官方接口、创意工坊实现指南。