ISteamUGC 订阅、下载与玩家交互接口
Steam 创意工坊项目从订阅到可加载需要经历状态检查和下载。本页面向游戏客户端和专用服务器开发者,整理 ISteamUGC 中订阅、安装、缓存、投票及游戏时间统计的接口与回调。
订阅与本地顺序
SubscribeItem和UnsubscribeItem:传项目 ID 管理用户订阅,返回异步调用句柄;分别处理RemoteStorageSubscribePublishedFileResult_t与RemoteStorageUnsubscribePublishedFileResult_t,检查结果和项目 ID。订阅变化还可观察UserSubscribedItemsListChanged_t。ISteamUGC 的订阅条目将结果名称写为旧更新结果,RemoteStorage 参考明确将订阅结果关联至SubscribeItem;请同时核对所用 SDK 头文件。取消订阅的内容在游戏退出后移除。GetNumSubscribedItems返回当前应用的订阅数量;GetSubscribedItems将 ID 写入数组并返回实际数量。两者默认不包含本地禁用项,可设置bIncludeLocallyDisabled;游戏服务器调用返回 0。SetItemsDisabledLocally:传项目 ID 数组、数量和禁用标志,设置本地禁用状态;返回bool,禁用不等于取消订阅。SetSubscriptionsLoadOrder:传 ID 数组及数量设置本地加载顺序;未列出的项目按订阅时间排序,返回bool。
状态、安装与下载
GetItemState:传项目 ID,返回可组合的EItemState位标志。已安装也可能需要更新;应使用位运算检查。DownloadItem:传项目 ID 与高优先级标志;返回true表示下载已开始,而非内容已可用。高优先级会暂停其他正在进行的 Steam 下载。等待DownloadItemResult_t并检查应用 ID、结果后再访问磁盘;未订阅项目可能只是临时缓存。GetItemDownloadInfo:传项目 ID,输出已下载和总字节数,返回bool;总数在下载开始后才有效。GetItemInstallInfo:传项目 ID 和输出缓冲区,获得大小、本地绝对路径及更新时间,返回是否已安装。调用还会将项目标记为用户使用过;旧项目的路径可能指向文件本身。SuspendDownloads:传布尔值暂停或恢复工坊下载;调用及恢复时机应与游戏对磁盘内容的访问协调。BInitWorkshopForGameServer:服务器在任何 UGC 命令前传 depot ID 和存储目录绝对路径,设置独立工坊目录;非服务器调用或工坊正在更新时返回false。
收到 ItemInstalled_t 时,应核对 m_unAppID 与 m_nPublishedFileId,再重新检查并加载。此回调发送给所有运行中的应用。DownloadItemResult_t 同样需要核对应用与项目及操作结果。
已下载缓存
GetNumDownloadedItems返回本地实际下载项目数;官方返回类型文字与函数声明不一致,应以 SDK 为准。GetDownloadedItems将 ID 写入指定容量的数组,返回写入数量;服务器调用返回 0。MarkDownloadedItemAsUnused传项目 ID,告知客户端不必继续保留其本地缓存;其他用户订阅时仍可能保留,返回bool。
收藏、投票与游戏时间
AddItemToFavorites和RemoveItemFromFavorites:传应用 ID 与项目 ID;异步结果为UserFavoriteItemsListChanged_t。SetUserItemVote:传项目 ID 和赞或踩的布尔值,异步返回SetUserItemVoteResult_t。GetUserItemVote:传项目 ID,异步读取GetUserItemVoteResult_t中的赞、踩及跳过标志。官方页面的部分描述与函数用途不符,应核对 SDK。StartPlaytimeTracking和StopPlaytimeTracking:传项目 ID 数组与数量,分别开始和停止统计,每次处理 1–100 项;通过对应结果中的m_eResult判断。停止跟踪会使对应项目的游戏时间会话次数加一。StopPlaytimeTrackingForAllItems:停止所有项目的跟踪,异步结果为StopPlaytimeTrackingResult_t。应用关闭时跟踪也会停止,使被跟踪项目的会话次数加一。
创意工坊协议状态
ShowWorkshopEULA 在叠加界面显示创意工坊协议;返回 bool,false 表示叠加界面无法显示。GetWorkshopEULAStatus 异步取得状态。处理 WorkshopEULAStatus_t 时检查结果、App ID、版本、签署时间、m_bAccepted 与 m_bNeedsAction:接受旧版本时前者也可能为真,因此要同时检查是否需要处理最新版本。