文獻 資源 新聞與更新 客服
語言
Steamworks 文獻庫
Steam 工作坊實作指南
Steamworks 文獻庫 > 功能 > 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 即可完成流程並發佈變更
備註：如要將可見度改為所有人皆可見，便必須完成工作坊檢查表的項目，包括品牌、標題、說明，以及至少一項公開物品。

技術總覽

有關使用 ISteamUGC API 來分享和取用使用者自製內容的流程資料，請查閱 Steamworks SDK 一文。 當中提供了如何分享在 Steam 工作坊或應用程式中找到的工作坊物品內容的方法。

工作坊 API 必須藉由 SteamUGC() 所傳回的指標才能存取。

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

在遊戲或應用程式中啟用 ISteamUGC

有兩項設定必須先完成，才能將工作坊物品上傳至 Steamworks 後端：設置 Steam 雲端配額，和啟用 ISteamUGC API。

Steam 雲端的用途是儲存工作坊物品的預覽圖片。 請依循下列步驟設置 Steam 雲端配額：
  1. 前往應用程式管理員控制版面的 Steam 雲端設定
  2. 將每位使用者的 Byte 配額以及每位使用者的檔案數量配額定為適合儲存預覽圖片的容量
  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，不要誤傳。
    • EWorkshopFileType 是一個列舉型別，用來定義社群中檔案的分享方式。 可選擇的值有：
      • k_EWorkshopFileTypeCommunity - 用來描述使用者上傳的檔案的型別，表示內容將分享至社群供所有人下載。 通常用來分享使用者建立的模組。
      • k_EWorkshopFileTypeMicrotransaction - 用來描述使用者上傳檔案的型別，但是視為官方內容新增至遊戲中。 這些檔案不會在工作坊中供使用者下載，但會在社群中供所有人評價。
        這也是《絕地要塞 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 工作坊的上傳流程。
    • 登錄 SubmitItemUpdateResult_t 的呼叫結果處理常式
    • 呼叫結果處理常式被執行時，檢查 m_eResult 確定上傳是否成功
    • 備註：一旦呼叫後，便無法取消物品的更新與上傳
  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 提供了可靈活列舉各種 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 參數（在第一步中設置）。

遊戲時間紀錄

若要紀錄一項工作坊物品的遊戲時間，只需以物品的 ID 呼叫 ISteamUGC::StartPlaytimeTracking 即可。 然後，停止使用物品時，再以物品的 ID 呼叫 ISteamUGC::StopPlaytimeTracking 來停止紀錄，或呼叫 ISteamUGC::StopPlaytimeTrackingForAllItems 即可一次停止所有物品的紀錄。
關閉應用程式時，遊戲時間紀錄也將同時停止。

您也可使用 ISteamUGC::CreateQueryAllUGCRequest 以不同的遊戲時間計量排序查詢結果。 以下是一些以遊戲時間排序的查詢法：

移除工作坊物品

呼叫 ISteamUGC::DeleteItem 移除工作坊物品。 請注意此動作並不會提示使用者，也不能還原。

Steamworks 範例——SpaceWar 整合

Steamworks SDK 中的 Steamworks API Example Application (SpaceWar) 展示了 ISteamUGC API 的一部分功能。
  • CSpaceWarClient::LoadWorkshopItem 演示了檢查工作坊物品是否下載並已安裝置磁碟中，和使用 ISteamRemoteStorage::PublishedFileId_t 要求一項工作坊物品的資訊。
  • CSpaceWarClient::LoadWorkshopItems 演示了如何取得目前在 SpaceWar 中的使用者的工作坊訂閱清單。
  • CSpaceWarClient::OnWorkshopItemInstalled 演示了一個 ISteamUGC::ItemInstalled_t 的回呼處理常式。

工作坊法律協議

在貢獻者同意 Steam 工作坊法律協議前，預設是無法公開工作坊物品的。 為了方便貢獻者公開他們的物品，請進行以下步驟：
  1. 在將物品提交至工作坊的按鈕旁邊，添增一段文字，類似於「提交物品的同時也表示您同意了工作坊服務條款」（包括連結）
  2. 使用者提交物品後，開啟瀏覽器視窗並導向至物品的 Steam 工作坊頁面。可呼叫 ISteamFriends::ActivateGameOverlayToWebPage 並將 pchURL 設為 steam://url/CommunityFilePage/<PublishedFileId_t> 然後將 <PublishedFileId_t> 替換為工作坊物品 ID
這麼做的好處是導向後方便作者看著頁面進行更多設定，以及便於閱讀與同意 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 上設定、管理，並營運您的遊戲。