文献库 资源 新闻与更新 客服
语言
Steamworks 文献库
Steam 创意工坊实现指南
Steamworks 文献库 > 功能 > Steam 创意工坊 > Steam 创意工坊实现指南

简介

Steam 创意工坊系统使用后端存储、前端网页的形式，便于存储、整理、排序、评分及下载游戏或应用程序。

本文提供了为产品实现 Steam 创意工坊的技术细节。 在开始将 Steam 创意工坊与您的游戏整合前，请参见 Steam 创意工坊概览，了解更多您能使用的各类创意工坊整合的定义及信息，以及如何最大程度利用 Steam 各类工具。

在一般情况下，您游戏的顾客会使用购买游戏时您提供的工具修改或创建全新的内容， 并将其通过工具内置表格提交给 Steam 创意工坊。 其他顾客可在 Steam 社区的 Steam 创意工坊中浏览、排序、评分或订阅希望增添至游戏中的物品， 并通过 Steam 下载这些物品。 如果您在游戏中注册了 ISteamUGC::ItemInstalled_t 回调，便可以调用 ISteamUGC::GetItemInstallInfo 获取安装位置并从该文件夹直接读取数据， 游戏便会以适合游戏及所创建内容的方式辨识新内容。

Steam 创意工坊类型、货币化及最佳实践

参见 Steam 创意工坊 一文，了解更多您能使用的各类创意工坊整合的定义及信息，以及如何最大程度利用 Steam 各类工具。

管理 Steam 创意工坊可见度

Steam 创意工坊是由 Steam 管理的网站，列出所有分享的内容，允许用户对社区中可见内容进行投票或留言。 应用程序在创意工坊中默认为不对公众开放可见， 以此防止不打算通过 Steam 创意工坊门户共享的内容被公开，除非将创意工坊设定为公开。
创意工坊可见状态的设置步骤如下：
  1. 打开 Steamworks 网站上的应用程序登录页面。
  2. 点击“编辑 Steamworks 设置”
  3. 在“创意工坊”选项卡中，选择“通用”
  4. 在页面右边，找到“可见状态”栏。
  5. 使用单选按钮选择可见度，可以为仅开发者可见、开发者和测试人员可见、顾客和开发者可见，以及所有人可见。
  6. 在“发布”选项卡中选择“准备发行”
  7. 点击“发布到 Steam”即可完成流程并发布变更。
注意：如果要将可见度更改为所有人可见，必须完成创意工坊清单上的项目，包括品牌、标题、描述等，并至少有一项内容公开可见。

技术概览

参见 Steamworks SDK，了解通过 ISteamUGC API 共享和消费用户生成内容的流程。 所公开的方法提供了分享创意工坊物品内容并可随后在 Steam 创意工坊或应用程序中找到相关内容的途径。

创意工坊 API 必须通过由 SteamUGC() 返回的指针才能访问。

示例：
SteamAPICall_t hSteamAPICall = SteamUGC()->CreateItem( SteamUtils()->GetAppID(), k_EWorkshopFileTypeMicrotransaction );

在游戏或应用程序中启用 ISteamUGC

将创意工坊物品上传至 Steamworks 后端之前，必须先设置两项配置，即配置 Steam 云配额、与启用 ISteamUGC API。

Steam 云用于存储与创意工坊物品相关的预览图片。 请按下列步骤配置 Steam 云配额：
  1. 前往应用管理员面板中的 Steam 云设置页面。
  2. 将“每个用户的字节配额”以及“每个用户的文件量配额”设置为适合储存预览图片的值。
  3. 点击“保存”
  4. 在“发布”选项卡中选择“准备发行”
  5. 点击“发布到 Steam”即可完成流程并发布变更。

启用 ISteamUGC API 步骤如下：
  1. 前往应用管理员面版中的 Steam 创意工坊配置页面。
  2. 找到“附加配置选项”栏目。
  3. 勾选“为文件传输启用 ISteamUGC”。
  4. 点击“保存”。
  5. 在“发布”选项卡中选择“准备发行”。
  6. 点击“发布到 Steam”即可完成流程并发布变更。
设置完成后即可通过 API 上传创意工坊物品。

创建并上传内容

创建并上传创意工坊内容流程简单，可重复进行，如下方的流程图所示。

ISteamUGCFlow-CreateUpload-Web2.png

创建创意工坊物品

  1. 所有创意工坊物品自调用 ISteamUGC::CreateItem 起开始存在。
    • nConsumerAppId 变量应包含游戏或应用程序的 App ID。 如果创意工坊物品创建工具有单独的 App ID，切勿传入该App ID。
    • EWorkshopFileType 为枚举类型，定义文件如何在社区中共享。 有效值为：
      • k_EWorkshopFileTypeCommunity：此类型文件用于描述由用户上传且可由社区内任何人下载的文件。 通常用于共享用户创建的模组。
      • k_EWorkshopFileTypeMicrotransaction：此类型文件用于描述由用户上传的文件，但其目的为仅供游戏决定是否添加入官方内容。 其他用户无法通过创意工坊下载该类型文件，但可在社区中查看并进行评价。
        Team Fortress 2 中也使用该实施方法。
  2. 注册一个 CreateItemResult_t 的调用结果处理程序。
  3. 首先查看 m_eResult，以确保物品已成功创建。
  4. 执行调用结果处理程序时，读取并保存 m_nPublishedFileId 值，以便将来更新创意工坊物品时可用（如保存于与创建工具相关的项目文件中）。
  5. 还应查看 m_bUserNeedsToAcceptWorkshopLegalAgreement 变量，如果为 true，需将用户重新定向至接受法律协议。 参见创意工坊法律协议，了解更多信息。

上传创意工坊物品

  1. 创意工坊物品创建完毕且 PublishedFileId_t 值返回后，即可填入创意工坊物品内容并上传至 Steam 创意工坊。
  2. 调用 ISteamUGC::StartItemUpdate 即可开始更新物品。
  3. 利用由 ISteamUGC::StartItemUpdate 所返回的 UGCUpdateHandle_t，可通过不同的ISteamUGC::SetItem[...] 方法进行调用，更新标题、描述、可见度、标签、物品内容和物品预览图片。
  4. 更新调用完成后，调用 ISteamUGC::SubmitItemUpdate 即可开始 Steam 创意工坊的上传流程。
  5. 如有需要，可使用 ISteamUGC::GetItemUpdateProgress 跟踪上传过程。
    • EItemUpdateStatus 定义了上传与更新过程。
    • punBytesProcessed 和 punBytesTotal 可用于提供用户界面控制输入，例如显示上传进度的进度栏。
    • punBytesTotal 可在上传进程中根据物品更新状态进行更新。
  6. 用创建创意工坊物品相同的方法，确认用户是否已接受法律协议， 以防用户并非该物品初创者，而是在对现有物品进行编辑。

附注

  • 创意工坊物品原先指定为单个文件。 但有了 ISteamUGC，创意工坊物品是包含文件的文件夹的表现形式。
  • 如果创意工坊物品因应用程序使用需要而需额外元数据，可调用 ISteamUGC::SetItemMetadata 将元数据加入物品。 这些元数据可从查询返回，无需下载安装实际内容。
    之前我们建议将该元数据存储于创意工坊物品文件夹内的一个文件当中，您仍可照样执行。

使用内容

使用创意工坊内容分为两类：物品订阅和物品安装。

物品订阅

绝大部分的创意工坊物品订阅通过 Steam 创意工坊门户进行。 这是对所有游戏与应用程序通用的已知位置，因此用户可在创意工坊网站上定期查找并订阅物品。

但 ISteamUGC 提供了两种方法，用编程方式订阅和取消订阅创意工坊物品，以支持对游戏中物品订阅的管理。

另外还有两个枚举用户已订阅物品的方法。

接收外部订阅操作通知

用户通过任何机制（如 ISteamUGC 或 Steam 创意工坊网站）订阅一个文件或取消订阅时，可收到游戏内通知。

物品安装

知晓物品订阅信息后，便可利用剩下的使用方法。 这些方法将物品下载与安装状态反馈回游戏， 然后基于下列规则，创意工坊物品通过 Steam 客户端自动下载：
  1. Steam 客户端即将启动游戏或应用程序时，便会下载并安装所有已更新的应用程序 depot。
  2. 如有需要，会更新所有现有已安装创意工坊物品。
  3. 启动游戏或应用程序。
  4. 新订阅但尚未下载的创意工坊物品将在后台进行下载与安装。
    • 已订阅文件将按订阅顺序下载至客户端。
    • 下载创意工坊物品时，Steam 的下载页面将以特定的横幅显示创意工坊物品正在下载。
注意：使用 Steam 客户端的“验证游戏文件完整性”功能也可导致下载创意工坊物品。

由于游戏会在新订阅物品下载并安装前启动，剩余的使用方法用于监控管理安装进度， 或是在游戏内订阅物品时用于提供实时安装状态。

创意工坊物品状态

创意工坊物品下载进度

开始下载创意工坊物品或提高其优先顺序

获取创意工坊物品本地副本信息

创意工坊物品已安装或更新通知

查询内容

ISteamUGC 接口提供了枚举各种 Steam UGC（如创意工坊物品、截图、视频等）的灵活方式。

ISteamUGCFlows-QueryingContent-web2.png

  1. 注册一个 SteamUGCQueryCompleted_t 调用结果处理程序。
  2. 根据情况不同可用不同方法进行查询，如查询与用户相关内容、查询所有内容或是以 ID 查询内容详情。
  3. 调用选项设置方法，自定义适合的查询：
  4. 使用 ISteamUGC::SendQueryUGCRequest 向 Steam 发送查询，会触发在第一步注册的 ISteamUGC::SteamUGCQueryCompleted_t 调用结果处理程序。
  5. 在 ISteamUGC::SteamUGCQueryCompleted_t 的调用结果处理程序中，调用 ISteamUGC::GetQueryUGCResult 来获取所返回的每项物品的详情。

  6. 您也可调用以下函数获取各物品的额外信息（有些数据不会默认返回，因此需妥善配置查询条件）：
  7. 调用 ISteamUGC::ReleaseQueryUGCRequest 释放查询或获取结果时分配的内存。

分页结果

每个查询可返回最多 50 项结果。 如果要对更多结果进行分页，可在查询中递增 unPage 参数（从 1 开始。）

游戏时间跟踪

要跟踪创意工坊物品的游戏时间，只需以所希望跟踪物品的 ID 调用ISteamUGC::StartPlaytimeTracking 即可。 随后物品从游戏移除时，再以物品 ID 调用 ISteamUGC::StopPlaytimeTracking 来停止跟踪，或调用 ISteamUGC::StopPlaytimeTrackingForAllItems 一次性停止所有物品跟踪。
关闭应用程序时，游戏时间跟踪自动停止。

您也可使用 ISteamUGC::CreateQueryAllUGCRequest 在查询中以不同的游戏时间指标对物品进行排序。 以下是基于游戏时间的查询法：

删除创意工坊物品内容

您可以调用 ISteamUGC::DeleteItem 来删除一件创意工坊物品。 请注意这样做将不会提示用户，且操作不可撤销。

Steamworks 示例：SpaceWar 集成

Steamworks SDK 中的 Steamworks API 示例应用程序（SpaceWar）展示了一个 ISteamUGC API 子集。
  • CSpaceWarClient::LoadWorkshopItem 展示了如何检查创意工坊物品是否已下载并安装至磁盘中，及如何使用 ISteamRemoteStorage::PublishedFileId_t 请求创意工坊物品信息。
  • CSpaceWarClient::LoadWorkshopItems 展示了如何获取当前用户为 SpaceWar 应用程序已订阅的创意工坊物品清单。
  • CSpaceWarClient::OnWorkshopItemInstalled 展示了一个 ISteamUGC::ItemInstalled_t 回调处理程序。

创意工坊法律协议

在贡献者同意《Steam 创意工坊法律协议》前，创意工坊物品默认为隐藏状态。 为方便贡献者公开他们的物品，请按以下步骤进行：
  1. 在将物品提交至创意工坊的按钮旁添增一段文字，类似于“提交此物品即表明您同意了创意工坊服务条款”（包括链接）。
  2. 用户提交物品后，调用 ISteamFriends::ActivateGameOverlayToWebPage，将 pchURL 设为 steam://url/CommunityFilePage/<PublishedFileId_t>，并将 <PublishedFileId_t> 替换为创意工坊物品 ID，以在浏览器窗口打开该物品的 Steam 创意工坊页面。
这样可将作者定向至创意工坊页面，以便作者查看物品，必要时也可进行更多配置。此外也便于用户阅读并接受《Steam 创意工坊法律协议》。

Web API

除上述方法外，Web API 接口也提供了类似功能，与基于社区的筛选 API 来一起列出所有分享内容。 请参阅 Web API 列表内的 ISteamRemoteStorage 接口文件。

专用游戏服务器

游戏服务器也可以用来下载和安装物品。
  • 游戏服务器需有 PublishedFileId_t 信息方可请求创意工坊物品。该信息可由游戏客户端提供，或由服务器管理员设置。 随后可调用 ISteamUGC::DownloadItem 获取创意工坊物品的临时副本。
  • 调用 ISteamUGC::GetItemInstallInfo 以获取定位信息并使用创意工坊物品。
  • 若需更多有关这些 API 方法的信息，请参见上述物品安装部分。

SteamCmd 集成

除 ISteamUGC API 之外，steamcmd.exe 命令行工具也可用于为测试目的创建和更新创意工坊物品。 由于此工具要求用户输入 Steam 凭据（我们不希望顾客提供），因此仅限于测试使用。

如要使用 steamcmd.exe 创建新的 Steam 创意工坊物品，首先须创建一个纯文本 VDF 文件， 并包含以下键值。
"workshopitem" { "appid" "480" "publishedfileid" "5674" "contentfolder" "D:\\Content\\workshopitem" "previewfile" "D:\\Content\\preview.jpg" "visibility" "0" "title" "Team Fortress Green Hat" "description" "A green hat for Team Fortress" "changenote" "Version 1.2" }

注意：
  • 键值与各种 ISteamUGC::SetItem[...] 方法对应。 请见上方文献了解更多信息。
  • 所示值为均为示例，应根据情况而适当调整。
  • 要创建新物品，则必须设置 appid，且 publishedfileid 必须不设，或设置为 0。
  • 要更新现有物品，appid 与 publishedfileid 均需设置。
  • 若要更新键值，剩余键/值对须包含在 VDF 文件中。
创建 VDF 后，可按 workshop_build_item <build config filename> 的文件参数运行 steamcmd.exe。 如：
steamcmd.exe +login myLoginName myPassword +workshop_build_item workshop_green_hat.vdf +quit
如果命令成功，VDF 中的 publishedfileid 值会自动更新，以包含创意工坊物品 ID。 由此，同一个 VDF 的 steamcmd.exe 后续调用将会更新而非创建新物品。

错误与日志

大部分 ISteamUGC 方法返回布尔值。 更多有关特定错误的信息，有多个地方可查阅：

常见问题

问：可以使用另一个应用程序将内容发布至我游戏的创意工坊吗？

可以。 可在基础应用程序的创意工坊对另一编辑或发布工具应用程序进行配置，以接受来自该应用程序的内容。

如要进行相关配置，请前往基础应用程序的创意工坊配置页面并滚动至页面底部， 在“应用发布权限”下方的字段中输入另一个应用程序的 App ID，然后点击“添加”。

发布 Steamworks 设置后，该编辑用应用程序即可将内容发布至基础程序的创意工坊。
Steamworks 是由 Valve 打造的一套工具和服务，帮助您在 Steam 上配置、管理和运营您的游戏。