ISteamUGC：回调、结构体与枚举

ISteamUGC 回调、结构体和枚举速查

ISteamUGC 回调和数据类型决定了 Steam 创意工坊异步操作如何交付结果。本页面向需要检查结果字段与状态的开发者，归纳官方文档中的回调、项目详情、枚举及句柄常量；具体定义应以项目使用的 SDK 为准。

创作者、Steam 工坊、玩家及游戏客户端之间的内容流

创建、更新与下载回调

  • CreateItemResult_t：包含 m_eResult、新项目 m_nPublishedFileId 和 m_bUserNeedsToAcceptWorkshopLegalAgreement。成功后保存 ID，并在需要时引导用户处理协议。
  • SubmitItemUpdateResult_t：包含结果和协议标志。失败可能涉及应用配置、许可证、文件路径、预览图大小、云空间或锁定；按实际 EResult 排查。
  • DeleteItemResult_t：删除操作的结果及项目标识。
  • DownloadItemResult_t：包含应用 ID、项目 ID 和结果；下载完成后核对三个字段再访问内容。
  • ItemInstalled_t：项目安装或更新时通知，包含应用 ID 和项目 ID，需过滤其他应用的通知。

查询和依赖回调

用户操作回调

项目详情结构体

SteamUGCDetails_t 由 GetQueryUGCResult 填充；每项应先检查 m_eResult。标题、描述、标签、文件名和 URL 在官方页面的类型列显示的是容量常量，下表按字符串缓冲区列示；精确声明和长度以所用 SDK 头文件为准。

字段 类型 含义
m_nPublishedFileId PublishedFileId_t 已发布项目的唯一 ID。
m_eResult EResult 这条详情的结果；先确认成功，再使用其他数据。
m_eFileType EWorkshopFileType 项目所属的文件类型。
m_nCreatorAppID AppId_t 创建项目所用的应用 ID。
m_nConsumerAppID AppId_t 使用该内容的应用 ID。
m_rgchTitle char[k_cchPublishedDocumentTitleMax] 项目标题字符串。
m_rgchDescription char[k_cchPublishedDocumentDescriptionMax] 项目描述字符串。
m_ulSteamIDOwner uint64 内容所有者的 Steam ID。
m_rtimeCreated uint32 创建时间，Unix 时间戳，单位秒。
m_rtimeUpdated uint32 最后更新时间，Unix 时间戳，单位秒。
m_rtimeAddedToUserList uint32 加入用户列表的 Unix 时间戳，单位秒；并非所有场景适用。
m_eVisibility ERemoteStoragePublishedFileVisibility 项目的可见性。
m_bBanned bool 项目是否被封禁。
m_bAcceptedForUse bool 应用开发者是否将该项目标记为已采纳。
m_bTagsTruncated bool 返回的标签列表是否因缓冲区长度被截断。
m_rgchTags char[k_cchTagListMax] 逗号分隔的标签列表。
m_hFile UGCHandle_t 主文件句柄。
m_hPreviewFile UGCHandle_t 预览文件句柄。
m_pchFileName char[k_cchFilenameMax] 主文件在 Steam 云中的文件名。
m_nFileSize int32 主文件大小，单位字节。
m_nPreviewFileSize int32 预览文件大小，单位字节。
m_rgchURL char[k_cchPublishedFileURLMax] 项目关联的 URL，例如视频或网页地址。
m_unVotesUp uint32 赞成票数。
m_unVotesDown uint32 反对票数。
m_flScore float 赞成票占比的贝叶斯平均评分，范围 0 到 1。
m_unNumChildren uint32 合集成员数或此项目的依赖项目数。

EItemState：项目状态位

GetItemState 返回可组合的位标志；安装与需要更新可以同时成立。使用位运算检查状态，而非只比较一个数值。

成员 值 用途
k_EItemStateNone 0 客户端未跟踪该项目。
k_EItemStateSubscribed 1 当前用户已订阅，不只是缓存。
k_EItemStateLegacyItem 2 由旧版 RemoteStorage 工坊接口创建。
k_EItemStateInstalled 4 内容已安装，但可能已经过期。
k_EItemStateNeedsUpdate 8 尚未安装或作者更新内容，需要更新。
k_EItemStateDownloading 16 更新正在下载。
k_EItemStateDownloadPending 32 下载已请求，等待下载完成通知后才能访问内容。

EItemUpdateStatus：上传阶段

GetItemUpdateProgress 返回当前阶段；最终结果仍由提交更新的调用结果确定。

成员 值 用途
k_EItemUpdateStatusInvalid 0 更新句柄无效；操作可能已完成，检查提交结果。
k_EItemUpdateStatusPreparingConfig 1 正在处理配置数据。
k_EItemUpdateStatusPreparingContent 2 正在读取和处理内容文件。
k_EItemUpdateStatusUploadingContent 3 正在上传内容更改。
k_EItemUpdateStatusUploadingPreviewFile 4 正在上传新预览图。
k_EItemUpdateStatusCommittingChanges 5 正在提交更改。

EItemPreviewType：预览类型

AddItemPreviewFile 不支持直接传入 YouTubeVideo 或 Sketchfab；YouTube 应使用视频预览接口。环境图支持 PNG、JPG、GIF。

成员 值 用途
k_EItemPreviewType_Image 0 网页可显示的普通图片，支持 PNG、JPG、GIF。
k_EItemPreviewType_YouTubeVideo 1 YouTube 视频 ID；使用视频预览接口添加。
k_EItemPreviewType_Sketchfab 2 Sketchfab 模型 ID。
k_EItemPreviewType_EnvironmentMap_HorizontalCross 3 水平十字布局的环境图；当前不用于网页视图。
k_EItemPreviewType_EnvironmentMap_LatLong 4 经纬布局的环境图；当前不用于网页视图。
k_EItemPreviewType_ReservedMax 255 保留值；官方允许在此值以上定义自有类型。

句柄与常量

UGCQueryHandle_t 和 UGCUpdateHandle_t 均为 uint64，分别标识查询与更新；查询使用完要释放。官方页面的 k_UGCQueryHandleInvalid 与 k_UGCUpdateHandleInvalid 均为 0xffffffffffffffffull；kNumUGCResultsPerPage 为 50，k_cchDeveloperMetadataMax 为 5000 字节。文档列出的接口版本字符串为 STEAMUGC_INTERFACE_VERSION015，使用不同 SDK 时应以其头文件为准。

查询类型完整枚举

以下为 SDK 的 EUGCMatchingUGCType，Web API 的文件类型枚举使用另一套数值。

成员 值 含义
k_EUGCMatchingUGCType_Items 0 鉴选型及即用型物品。
k_EUGCMatchingUGCType_Items_Mtx 1 鉴选型物品。
k_EUGCMatchingUGCType_Items_ReadyToUse 2 即用型物品。
k_EUGCMatchingUGCType_Collections 3 合集。
k_EUGCMatchingUGCType_Artwork 4 艺术作品。
k_EUGCMatchingUGCType_Videos 5 视频。
k_EUGCMatchingUGCType_Screenshots 6 截图。
k_EUGCMatchingUGCType_AllGuides 7 所有指南。
k_EUGCMatchingUGCType_WebGuides 8 网页指南。
k_EUGCMatchingUGCType_IntegratedGuides 9 游戏内集成指南。
k_EUGCMatchingUGCType_UsableInGame 10 即用物品及集成指南。
k_EUGCMatchingUGCType_ControllerBindings 11 控制器绑定。
k_EUGCMatchingUGCType_GameManagedItems 12 游戏管理项目。
k_EUGCMatchingUGCType_All ~0 所有类型。

EUGCQuery 指定全局查询排序；趋势期通过 SetRankedByTrendDays 设置。

成员 值 含义
k_EUGCQuery_RankedByVote 0 按历史投票热度。
k_EUGCQuery_RankedByPublicationDate 1 按发布日期降序。
k_EUGCQuery_AcceptedForGameRankedByAcceptanceDate 2 已采纳物品按采纳日期。
k_EUGCQuery_RankedByTrend 3 按趋势期投票热度。
k_EUGCQuery_FavoritedByFriendsRankedByPublicationDate 4 好友收藏，按发布日期。
k_EUGCQuery_CreatedByFriendsRankedByPublicationDate 5 好友创建，按发布日期。
k_EUGCQuery_RankedByNumTimesReported 6 按举报权重降序。
k_EUGCQuery_CreatedByFollowedUsersRankedByPublicationDate 7 关注用户创建，按发布日期。
k_EUGCQuery_NotYetRated 8 当前用户的投票队列。
k_EUGCQuery_RankedByTotalVotesAsc 9 总票数升序。
k_EUGCQuery_RankedByVotesUp 10 赞数降序，可使用趋势期。
k_EUGCQuery_RankedByTextSearch 11 文本搜索相关度。
k_EUGCQuery_RankedByTotalUniqueSubscriptions 12 历史去重订阅数降序。
k_EUGCQuery_RankedByPlaytimeTrend 13 趋势期总游戏时间。
k_EUGCQuery_RankedByTotalPlaytime 14 累计游戏时间。
k_EUGCQuery_RankedByAveragePlaytimeTrend 15 趋势期平均游戏时间。
k_EUGCQuery_RankedByLifetimeAveragePlaytime 16 历史平均游戏时间。
k_EUGCQuery_RankedByPlaytimeSessionsTrend 17 趋势期会话数。
k_EUGCQuery_RankedByLifetimePlaytimeSessions 18 累计会话数。
k_EUGCQuery_RankedByLastUpdatedDate 19 最近更新时间。
k_EUGCQuery_RankedByNumParentItems 20 依赖该项目的项目数量。
k_EUGCRankedByNumParentCollections 21 包含该项目的合集数量。

最后一项符号按官方页面原样列出；SDK 版本可能有差异，编译时以头文件为准。

用户列表和排序枚举

EUserUGCList 指定用户项目列表。投票和订阅等部分列表限当前用户；WillVoteLater 已弃用。

成员 值 含义
k_EUserUGCList_Published 0 已发布项目。
k_EUserUGCList_VotedOn 1 已投票项目。
k_EUserUGCList_VotedUp 2 已赞项目。
k_EUserUGCList_VotedDown 3 已踩项目。
k_EUserUGCList_WillVoteLater 4 已弃用。
k_EUserUGCList_Favorited 5 收藏项目。
k_EUserUGCList_Subscribed 6 订阅项目。
k_EUserUGCList_UsedOrPlayed 7 使用或玩过的项目。
k_EUserUGCList_Followed 8 关注更新的项目。

EUserUGCListSortOrder 控制用户列表顺序。

成员 值 含义
k_EUserUGCListSortOrder_CreationOrderDesc 0 创建时间降序。
k_EUserUGCListSortOrder_CreationOrderAsc 1 创建时间升序。
k_EUserUGCListSortOrder_TitleAsc 2 标题升序。
k_EUserUGCListSortOrder_LastUpdatedDesc 3 最近更新优先。
k_EUserUGCListSortOrder_SubscriptionDateDesc 4 最近订阅优先。
k_EUserUGCListSortOrder_VoteScoreDesc 5 评分排序。
k_EUserUGCListSortOrder_ForModeration 6 返回待审核举报项目。

项目统计枚举

EItemStatistic 传给 GetQueryUGCStatistic。

成员 值 含义
k_EItemStatistic_NumSubscriptions 0 订阅数。
k_EItemStatistic_NumFavorites 1 收藏数。
k_EItemStatistic_NumFollowers 2 关注数。
k_EItemStatistic_NumUniqueSubscriptions 3 去重订阅数。
k_EItemStatistic_NumUniqueFavorites 4 去重收藏数。
k_EItemStatistic_NumUniqueFollowers 5 去重关注数。
k_EItemStatistic_NumUniqueWebsiteViews 6 项目页面去重浏览量。
k_EItemStatistic_ReportScore 7 举报次数。
k_EItemStatistic_NumSecondsPlayed 8 累计游戏秒数。
k_EItemStatistic_NumPlaytimeSessions 9 累计游戏会话数。
k_EItemStatistic_NumComments 10 评论数。
k_EItemStatistic_NumSecondsPlayedDuringTimePeriod 11 指定时间段游戏秒数。
k_EItemStatistic_NumPlaytimeSessionsDuringTimePeriod 12 指定时间段游戏会话数。

EUGCContentDescriptorID：内容描述词

这些值用于标记项目并配合 Steam 的用户内容筛选；选择值时应准确反映项目内容。读取使用 GetQueryUGCContentDescriptors，更改使用 AddContentDescriptor 和 RemoveContentDescriptor。

成员 值 用途
k_EUGCContentDescriptor_NudityOrSexualContent 1 内容分类标记 1。
k_EUGCContentDescriptor_FrequentViolenceOrGore 2 内容分类标记 2。
k_EUGCContentDescriptor_AdultOnlySexualContent 3 内容分类标记 3；查看时有年龄确认要求。
k_EUGCContentDescriptor_GratuitousSexualContent 4 内容分类标记 4；查看时有年龄确认要求。
k_EUGCContentDescriptor_AnyMatureContent 5 内容分类标记 5。

项目类型和可见性

EWorkshopFileType 定义共享文件类型，创建工坊项目时应选择适用类型。

成员 值 含义
k_EWorkshopFileTypeFirst 0 枚举起点。
k_EWorkshopFileTypeCommunity 0 可订阅的普通工坊项目。
k_EWorkshopFileTypeMicrotransaction 1 用于鉴选的物品。
k_EWorkshopFileTypeCollection 2 合集。
k_EWorkshopFileTypeArt 3 艺术作品。
k_EWorkshopFileTypeVideo 4 外部视频。
k_EWorkshopFileTypeScreenshot 5 截图。
k_EWorkshopFileTypeGame 6 未使用的历史游戏类型。
k_EWorkshopFileTypeSoftware 7 未使用的历史软件类型。
k_EWorkshopFileTypeConcept 8 未使用的历史概念类型。
k_EWorkshopFileTypeWebGuide 9 网页指南。
k_EWorkshopFileTypeIntegratedGuide 10 应用内集成指南。
k_EWorkshopFileTypeMerch 11 需投票选择的商品。
k_EWorkshopFileTypeControllerBinding 12 控制器绑定。
k_EWorkshopFileTypeSteamworksAccessInvite 13 Steam 内部使用。
k_EWorkshopFileTypeSteamVideo 14 Steam 视频。
k_EWorkshopFileTypeGameManagedItem 15 游戏管理且不在网页显示的项目。
k_EWorkshopFileTypeMax 16 枚举边界。

ERemoteStoragePublishedFileVisibility 可用于 SetItemVisibility。

成员 值 含义
k_ERemoteStoragePublishedFileVisibilityPublic 0 所有人可见。
k_ERemoteStoragePublishedFileVisibilityFriendsOnly 1 好友可见。
k_ERemoteStoragePublishedFileVisibilityPrivate 2 仅作者可见。
k_ERemoteStoragePublishedFileVisibilityUnlisted 3 可见但不出现在全局查询；用户列表有作者和订阅者例外。

RemoteStorage 相关类型和长度常量

PublishedFileId_t 是 uint64 项目唯一标识；k_PublishedFileIdInvalid 为 0。SteamParamStringArray_t 包含 m_ppStrings 字符串指针数组和 m_nNumStrings 数量，用于传入标签等字符串集合。

常量 官方值 用途
k_cchPublishedDocumentTitleMax 128 + 1 项目标题长度上限，单位字节。
k_cchPublishedDocumentDescriptionMax 8000 项目描述长度上限，单位字节。
k_cchPublishedFileURLMax 256 项目 URL 长度上限，单位字节。
k_cchTagListMax 1024 + 1 逗号分隔的标签列表长度上限，单位字节。
k_cchFilenameMax 260 Steam 云文件路径长度上限。

这些是 SDK 常量而非界面字符数；多字节文本应按字节处理，并以所用 SDK 版本的定义为准。

提交更新的常见结果

SubmitItemUpdateResult_t 中的 m_eResult 用于区分成功与错误；先处理异步传输失败，再检查该字段。

结果 官方列出的常见原因或排查方向
k_EResultOK 提交成功；仍需检查是否要求用户接受协议。
k_EResultFail 一般性失败，结合日志和操作阶段排查。
k_EResultInvalidParam App ID 无效或不匹配、未启用 ISteamUGC，或预览文件小于 16 字节。
k_EResultAccessDenied 用户没有所提供 App ID 的许可证。
k_EResultFileNotFound 工坊项目信息、预览文件或内容目录无法找到或读取。
k_EResultLockingFailed 无法取得 UGC 锁。
k_EResultLimitExceeded 预览图过大，或用户 Steam 云空间不足；官方要求预览图小于 1 MB。

回调结构的逐字段说明见站内回调参考。

资料来源：ISteamUGC 官方接口、ISteamRemoteStorage 官方接口。