Introduction

Steam Workshop is a system of back-end storage and front-end web pages that make it easy to store, organize, sort, rate, and download content for your game or application.

This page contains technical details on implementing Steam Workshop with your title. For information and definitions of the various types of Workshop integration you can utilize and how to make the best out of the tools provided by Steam please see the Steam Workshop Overview before getting started integrating the steam workshop with your game.

In a typical set-up, customers of your game would use tools provided by you with purchase of your game to create modifications or entirely new content. Those customers would then submit that content through a form built into your tool to the Steam Workshop. Other customers would then be able to browse, sort, rate, and subscribe to items they wish to add to their game by going to the Steam Workshop in the Steam Community. Those items would then download through Steam. If you've registered for the ISteamUGC::ItemInstalled_t callback within your game, you can then call ISteamUGC::GetItemInstallInfo to get the installed location and read the data directly from that folder. That new content would then be recognized by the game in whatever capacity makes sense for your game and the content created.

Steam Workshop Types, Monetization, & Best Practices

For more information and definitions of the various types of Workshop integration you can utilize and how to make the best out of the tools provided by Steam, please see the Steam Workshop documentation.

Managing Steam Workshop Visibility

The Steam Workshop is the website hosted through Steam that enumerates shared content and allows users to vote and comment on the content visible through the community. By default, applications are not enabled to be publicly visible in the Workshop. This prevents content not intended to be shared through the Steam Workshop portal from being visible unless the workshop is set to public.
Set the visibility state of the workshop through the following steps:

1. Browse to the application landing page on the Steamworks website
   
2. Click Edit Steamworks Settings
   
3. From the Workshop Tab, select General
   
4. On the right-hand side of the page, find the Visibility State section.
   
5. Use the radio buttons to select the desired level of visibility which can include Developers Only, Developers & Testers, Customers & Developers and Everyone.
   
6. From the Publish tab, click Prepare for Publishing
   
7. Click Publish to Steam and complete the process to publish the change.

Note: To change the visibility state to Everyone, the Workshop checklist must be complete which includes branding, title, description and at least one item of content publicly visible.

Tech Overview

The process to share and consume User Generated Content is by using the ISteamUGC API which can be found in the Steamworks SDK. The methods exposed provide a way to share workshop item content which can then be discovered through the Steam Workshop or an in-app experience.

The Workshop API must be accessed through the pointer that is returned from SteamUGC().

For example:

Enabling ISteamUGC for a Game or Application

Before workshop items can be uploaded to the Steamworks backend there are two configuration settings that must be made, Configuring Steam Cloud Quotas and Enabling the ISteamUGC API.

The Steam Cloud feature is used to store the preview images associated to workshop items. The Steam Cloud Quota can be configured with the following steps:

1. Navigate to the Steam Cloud Settings page in the App Admin panel.
   
2. Set the Byte quota per user and Number of files allowed per user to appropriate values for preview image storage
   
3. Click Save
   
4. From the Publish tab, click Prepare for Publishing
   
5. Click Publish to Steam and complete the process to publish the change.

Enabling the ISteamUGC API can be accomplished with the following steps:

1. Navigate to the Steam Workshop Configuration page in the App Admin panel.
   
2. Find the Additional Configuration Options section.
   
3. Check Enable ISteamUGC for file transfer.
   
4. Click Save.
   
5. From the Publish tab, click Prepare for Publishing.
   
6. Click Publish to Steam and complete the process to publish the change.

Once these settings are in place workshop content can be uploaded via the API.

Creating and Uploading Content

The process of creating and uploading workshop content is a simple and repeatable process as shown in the flow chart below.

Creating a Workshop Item

1. All workshop items begin their existence with a call to ISteamUGC::CreateItem
   
   • The nConsumerAppId variable should contain the App ID for the game or application. Do not pass the App ID of the workshop item creation tool if that is a separate App ID.
     
   • EWorkshopFileType is an enumeration type that defines how the shared file will be shared with the community. The valid values are:
     
     • k_EWorkshopFileTypeCommunity - This file type is used to describe files that will be uploaded by users and made available to download by anyone in the community. Common usage of this would be to share user created mods.
       
     • k_EWorkshopFileTypeMicrotransaction - This file type is used to describe files that are uploaded by users, but intended only for the game to consider adding as official content. These files will not be downloaded by users through the Workshop, but will be viewable by the community to rate.
       This is the implementation that Team Fortress 2 uses.
       
2. Register a call result handler for CreateItemResult_t
   
3. First check the m_eResult to ensure that the item was created successfully.
   
4. When the call result handler is executed, read the m_nPublishedFileId value and store for future updates to the workshop item (e.g. in a project file associated with the creation tool).
   
5. The m_bUserNeedsToAcceptWorkshopLegalAgreement variable should also be checked and if it's true, the user should be redirected to accept the legal agreement. See the Workshop Legal Agreement section for more details.

Uploading a Workshop Item

1. Once a workshop item has been created and a PublishedFileId_t value has been returned, the content of the workshop item can be populated and uploaded to the Steam Workshop.
   
2. An item update begins with a call to ISteamUGC::StartItemUpdate
   
3. Using the UGCUpdateHandle_t that is returned from ISteamUGC::StartItemUpdate, calls can be made to update the Title, Description, Visibility, Tags, Item Content and Item Preview Image through the various ISteamUGC::SetItem[...] methods.
   
   • ISteamUGC::SetItemTitle - Sets a new title for an item.
     
   • ISteamUGC::SetItemDescription - Sets a new description for an item.
     
   • ISteamUGC::SetItemUpdateLanguage - Sets the language of the title and description that will be set in this item update.
     
   • ISteamUGC::SetItemMetadata - Sets arbitrary metadata for an item. This metadata can be returned from queries without having to download and install the actual content.
     
   • ISteamUGC::SetItemVisibility - Sets the visibility of an item.
     
   • ISteamUGC::SetItemTags - Sets arbitrary developer specified tags on an item.
     
   • ISteamUGC::AddItemKeyValueTag - Adds a key-value tag pair to an item. Keys can map to multiple different values (1-to-many relationship).
     
   • ISteamUGC::RemoveItemKeyValueTags - Removes an existing key value tag from an item.
     
   • ISteamUGC::SetItemContent - Sets the folder that will be stored as the content for an item.
     
   • ISteamUGC::SetItemPreview -Sets the primary preview image for the item.
4. Once the update calls have been completed, calling ISteamUGC::SubmitItemUpdate will initiate the upload process to the Steam Workshop.
   
   • Register a call result handler for SubmitItemUpdateResult_t
     
   • When the call result handler is executed, check the m_eResult to confirm the upload completed successfully.
     
   • Note: There is no method to cancel the item update and upload once it's been called.
5. If desired, the progress of the upload can be tracked using ISteamUGC::GetItemUpdateProgress
   
   • EItemUpdateStatus defines the upload and update progress.
     
   • punBytesProcessed and punBytesTotal can be used to provide input for a user interface control such as a progress bar to indicate progress of the upload.
     
   • punBytesTotal may update during the upload process based upon the stage of the item update.
6. In the same way as Creating a Workshop Item, confirm the user has accepted the legal agreement. This is necessary in case where the user didn't initially create the item but is editing an existing item.

Additional Notes

• Workshop items were previously designated as single files. With ISteamUGC, a workshop item is a representation of a folder of files.
  
• If a workshop item requires additional metadata for use by the consuming application, you can attach metadata to your item using the ISteamUGC::SetItemMetadata call. This metadata can be returned in queries without having to download and install the item content.
  Previously we suggested that you save this metadata to a file inside the workshop item folder, which of course you can still do.

Consuming Content

Consuming workshop content falls into two categories, Item Subscription and Item Installation.

Item Subscription

The majority of subscriptions to a workshop item will happen through the Steam Workshop portal. It is a known location, common to all games and applications, and as such, users are likely to find and subscribe to items regularly on the workshop site.

However, ISteamUGC provides two methods for programmatically subscribing and unsubscribing to workshop items to support in-game item subscription management.

• ISteamUGC::SubscribeItem - Subscribe to a workshop item. It will be downloaded and installed as soon as possible.
  
• ISteamUGC::UnsubscribeItem - Unsubscribe from a workshop item. This will result in the item being removed after the game quits.

Two additional methods exist for enumerating through a user's subscribed items.

• ISteamUGC::GetNumSubscribedItems - Gets the total number of items the current user is subscribed to for the game or application.
  
• ISteamUGC::GetSubscribedItems - Gets a list of all of the items the current user is subscribed to for the current game.

Receiving Notifications for External Subscription Actions

In-game notifications can be received when a user has subscribed or unsubscribed from a file through any mechanism (e.g. ISteamUGC, Steam Workshop Website):

• Register a callback handler for RemoteStoragePublishedFileSubscribed_t and RemoteStoragePublishedFileUnsubscribed_t
  
• The structs will be populated with the ISteamRemoteStorage::PublishedFileId_t which can then be used to access the information about the workshop item.
  
• The structs also contain the application ID (m_unAppID) associated with the workshop item. It should be compared against the running application ID as the handler will be called for all item subscriptions regardless of the running application.

Item Installation

Once Item Subscription information is known, the remaining consumption methods can be utilized. These methods provide information back to the game about the state of the item download and installation. Workshop item downloads are executed via the Steam Client and happen automatically, based on the following rules:

1. When the Steam Client indicates a game or application is to launch, all app depots that have been updated will be downloaded and installed.
   
2. Any existing installed workshop items are updated if needed
   
3. Game or application then launches
   
4. Newly subscribed workshop items that are not downloaded will then download and be installed in the background.
   
   • Subscribed files will be downloaded to the client in the order they were subscribed in.
     
   • The Steam download page will show workshop item downloads with a specific banner to indicate a workshop item download is occurring.

Note: Using the "Verify Integrity of Game Files" feature in the Steam Client will also cause workshop items to be downloaded.

As the game will start before newly subscribed content is downloaded and installed, the remaining consumption methods exist to aid in monitoring and managing the install progress. They can also be used when items are subscribed in-game to provide status of installation in real time.

Status of a Workshop Item

• ISteamUGC::GetItemState - Gets the current state of a workshop item on this client.

Download Progress of a Workshop Item

• ISteamUGC::GetItemDownloadInfo - Get info about a pending download of a workshop item that has k_EItemStateNeedsUpdate set.

Initiate or Increase the Priority of Downloading a Workshop Item

• ISteamUGC::DownloadItem
  
  • Set bHighPriority to true to pause any existing in-progress downloads and immediately begin downloading this workshop item.
    
  • If the return value is true then register and wait for the callback ISteamUGC::DownloadItemResult_t before calling ISteamUGC::GetItemInstallInfo or accessing the workshop item on disk.
    
  • If the user is not subscribed to the item (e.g. a Game Server using anonymous login), the workshop item will be downloaded and cached temporarily.
    
  • If the workshop item has an ISteamUGC::EItemState of k_EItemStateNeedsUpdate, ISteamUGC::DownloadItem can be called to initiate the update. Do not access the workshop item on disk until the callback ISteamUGC::DownloadItemResult_t is called.
    
  • This method only works with ISteamUGC created workshop items. It will not work with legacy ISteamRemoteStorage workshop items.
    
  • The ISteamUGC::DownloadItemResult_t callback struct contains the application ID (m_unAppID) associated with the workshop item. It should be compared against the running application ID as the handler will be called for all item downloads regardless of the running application.

Retrieving information about the local copy of the Workshop Item

• ISteamUGC::GetItemInstallInfo - Gets info about currently installed content on the disc for workshop items that have k_EItemStateInstalled set.

Notification when a Workshop Item is Installed or Updated

• Register a callback handler for ISteamUGC::ItemInstalled_t.

Querying Content

The ISteamUGC interface provides a flexible way to enumerate the various kinds of UGC in Steam (e.g. Workshop items, screenshots, videos, etc.).

1. Register a call result handler for SteamUGCQueryCompleted_t.
   
2. There are a few methods available for creating the query depending upon the required scenario, Querying by Content Associated to a User or Querying All Content or getting the details of content you have ids for.
   
   • ISteamUGC::CreateQueryUserUGCRequest - Query UGC associated with a user. You can use this to list the UGC the user is subscribed to amongst other things.
     
   • ISteamUGC::CreateQueryAllUGCRequest - Query for all matching UGC. You can use this to list all of the available UGC for your app.
     
   • ISteamUGC::CreateQueryUGCDetailsRequest - Query for the details of specific workshop items.
     
3. Customize the query as appropriate by calling the option setting methods:
   
   • When querying for User UGC
     
     • ISteamUGC::SetCloudFileNameFilter - Sets to only return items that have a specific filename on a pending UGC Query.
       
   • When querying for All UGC
     
     • ISteamUGC::SetMatchAnyTag - Sets whether workshop items will be returned if they have one or more matching tag, or if all tags need to match on a pending UGC Query.
       
     • ISteamUGC::SetSearchText - Sets a string to that items need to match in either the title or the description on a pending UGC Query.
       
     • ISteamUGC::SetRankedByTrendDays - Sets whether the order of the results will be updated based on the rank of items over a number of days on a pending UGC Query.
       
   • When querying for either type of UGC
     
     • ISteamUGC::AddRequiredTag - Adds a required tag to a pending UGC Query. This will only return UGC with the specified tag.
       
     • ISteamUGC::AddExcludedTag - Adds a excluded tag to a pending UGC Query. This will only return UGC without the specified tag.
       
     • ISteamUGC::AddRequiredKeyValueTag - Adds a required key-value tag to a pending UGC Query. This will only return workshop items that have a key = [param]pKey[/param] and a value = [param]pValue[/param].
       
     • ISteamUGC::SetReturnOnlyIDs - Sets whether to only return IDs instead of all the details on a pending UGC Query. This is useful for when you don't need all the information (e.g. you just want to get the IDs of the items a user has in their favorites list.)
       
     • ISteamUGC::SetReturnKeyValueTags - Sets whether to return any key-value tags for the items on a pending UGC Query.
       
     • ISteamUGC::SetReturnLongDescription - Sets whether to return the full description for the items on a pending UGC Query.
       
     • ISteamUGC::SetReturnMetadata - Sets whether to return the developer specified metadata for the items on a pending UGC Query.
       
     • ISteamUGC::SetReturnChildren - Sets whether to return the IDs of the child items of the items on a pending UGC Query.
       
     • ISteamUGC::SetReturnAdditionalPreviews - Sets whether to return any additional images/videos attached to the items on a pending UGC Query.
       
     • ISteamUGC::SetReturnTotalOnly - Sets whether to only return the total number of matching items on a pending UGC Query. -- The actual items will not be returned when ISteamUGC::SteamUGCQueryCompleted_t is called.
       
     • ISteamUGC::SetLanguage - Sets the language to return the title and description in for the items on a pending UGC Query.
       
     • ISteamUGC::SetAllowCachedResponse - Sets whether results to be will be returned from the cache for the specific period of time on a pending UGC Query.
       
4. Send the query to Steam using ISteamUGC::SendQueryUGCRequest which will invoke the ISteamUGC::SteamUGCQueryCompleted_t call result handler registered in step 1.
   
5. In the call result handler for ISteamUGC::SteamUGCQueryCompleted_t, call ISteamUGC::GetQueryUGCResult to retrieve the details for each item returned.
   
   
6. You can also call these functions to retrieve additional information for each item (some of this data is not returned by default, so you need to configure your query appropriately):
   
   • ISteamUGC::GetQueryUGCPreviewURL - Retrieve the URL to the preview image of an individual workshop item after receiving a querying UGC call result.
     
   • ISteamUGC::GetQueryUGCMetadata - Retrieve the developer set metadata of an individual workshop item after receiving a querying UGC call result.
     
   • ISteamUGC::GetQueryUGCChildren - Retrieve the ids of any child items of an individual workshop item after receiving a querying UGC call result.
     
   • ISteamUGC::GetQueryUGCStatistic - Retrieve various statistics of an individual workshop item after receiving a querying UGC call result.
     
   • ISteamUGC::GetQueryUGCNumAdditionalPreviews and ISteamUGC::GetQueryUGCAdditionalPreview - Retrieve the details of an additional preview associated with an individual workshop item after receiving a querying UGC call result.
     
   • ISteamUGC::GetQueryUGCNumKeyValueTags and ISteamUGC::GetQueryUGCKeyValueTag - Retrieve the details of a key-value tag associated with an individual workshop item after receiving a querying UGC call result.
     
7. Call ISteamUGC::ReleaseQueryUGCRequest to free up any memory allocated while querying or retrieving the results.

Paging Results

Up to 50 results will be returned from each query. Paging through more results can be achieved by creating a query that increments the unPage parameter (which should start at 1).

Playtime Tracking

To track the playtime of Workshop items simply call ISteamUGC::StartPlaytimeTracking with the ids of the items you want to track. Then when the items are removed from play call ISteamUGC::StopPlaytimeTracking with the ids you want to stop tracking or call ISteamUGC::StopPlaytimeTrackingForAllItems to stop tracking playtime for all items at once.
When your app shuts down, playtime tracking will automatically stop.

You will also be able to sort items by various playtime metrics in ISteamUGC::CreateQueryAllUGCRequest queries. Here are the playtime based query types you can use:

• k_EUGCQuery_RankedByPlaytimeTrend - Sort by total playtime in the "trend" period descending (set with ISteamUGC::SetRankedByTrendDays)
  
• k_EUGCQuery_RankedByTotalPlaytime - Sort by total lifetime playtime descending.
  
• k_EUGCQuery_RankedByAveragePlaytimeTrend - Sort by average playtime in the "trend" period descending (set with ISteamUGC::SetRankedByTrendDays)
  
• k_EUGCQuery_RankedByLifetimeAveragePlaytime - Sort by lifetime average playtime descending
  
• k_EUGCQuery_RankedByPlaytimeSessionsTrend - Sort by number of play sessions in the "trend" period descending (set in ISteamUGC::SetRankedByTrendDays)
  
• k_EUGCQuery_RankedByLifetimePlaytimeSessions - Sort by number of lifetime play sessions descending

Deleting Workshop Item Content

To delete a Workshop item, you can call ISteamUGC::DeleteItem. Please note that this does not prompt the user and cannot be undone.

Steamworks Example – SpaceWar Integration

The Steamworks API Example Application (SpaceWar) that comes with the Steamworks SDK demonstrates a subset of the ISteamUGC API.

• CSpaceWarClient::LoadWorkshopItem demonstrates checking if a workshop item is downloaded and installed on disk as well as requesting information about a workshop item by ISteamRemoteStorage::PublishedFileId_t
  
• CSpaceWarClient::LoadWorkshopItems demonstrates retrieving the list of subscribed workshop items for the current user for the SpaceWar application
  
• CSpaceWarClient::OnWorkshopItemInstalled demonstrates a callback handler for ISteamUGC::ItemInstalled_t

Workshop Legal Agreement

Workshop items will be hidden by default until the contributor agrees to the Steam Workshop Legal Agreement. In order to make it easy for the contributor to make the item publicly visible, please do the following.

1. Include text next to the button that submits an item to the workshop, something to the effect of: "By submitting this item, you agree to the workshop terms of service" (including the link)
   
2. After a user submits an item, open a browser window to the Steam Workshop page for that item by calling ISteamFriends::ActivateGameOverlayToWebPage with pchURL set to steam://url/CommunityFilePage/<PublishedFileId_t> replacing <PublishedFileId_t> with the workshop item id.

This has the benefit of directing the author to the workshop page so that they can see the item and configure it further if necessary and will make it easy for the user to read and accept the Steam Workshop Legal Agreement.

Web API

In addition to these methods, there are a set of Web API interface that provides similar functionality along with community-based filtering APIs to list all shared content. Please consult the documentation for the ISteamRemoteStorage interface in the Web API list.

Dedicated Game Servers

Game servers can also download and install items.

• The Game Server will need to know the PublishedFileId_t to request a workshop item, this could be supplied by the game clients or set by the server operator. Then call ISteamUGC::DownloadItem to retrieve a temporary copy of the workshop item.
  
• A call can then be made to ISteamUGC::GetItemInstallInfo to retrieve information to locate and use the workshop item.
  
• See the Item Installation section above for more information on these API methods.

SteamCmd Integration

Along with the ISteamUGC API, the steamcmd.exe command line tool can be used to create and update workshop items for testing purposes. This should only be used for testing purposes, as the tool requires the user to enter their Steam credentials (something we don't want customers to have to do).

To create a new Steam Workshop item using steamcmd.exe a VDF file must first be created. The VDF is a plain text file that should contain the following keys.

Notes:

• The keys map to the various ISteamUGC::SetItem[...] methods. See the documentation above for more details.
  
• The values shown are examples only and should be updated appropriately.
  
• To create a new item, appid must be set and publishedfileid must be unset or set to 0.
  
• To update an existing item, appid and publishedfileid must both be set.
  
• The remaining key/value pairs should be included in the VDF if the key should be updated.

Once the VDF has been created, steamcmd.exe can be run with the workshop_build_item <build config filename> file parameter. For example:
If the command is successful, the publishedfileid value in the VDF will be automatically updated to contain the ID of the workshop item. In this way, subsequent calls with steamcmd.exe for the same VDF will result in an update rather than creation of a new item.

Errors and Logging

The majority of ISteamUGC methods return boolean values. For additional information on specific errors, there are a number of places to review:

• Steam\logs\Workshop_log.txt is a log for all transfers that occur during workshop item downloading
  and installation.
  
• Steam\workshopbuilds\depot_build_<appid>.log is a log for all actions during the upload and update of a workshop item.
  
• ISteamUGC::SteamUGCQueryCompleted_t, ISteamUGC::CreateItemResult_t and ISteamUGC::SubmitItemUpdateResult_t contain EResult variables that can be checked.

Frequently Asked Questions

Q: Can a separate application publish content to my game's Workshop?

Yes. A separate application for editing or publishing tools can be configured with base application's workshop to accept content from that editing application.

To configure this, go to the Workshop Configuration section for the base application and scroll to the bottom of the page. Enter the separate application's App ID in the field under "App Publish Permissions" and hit "Add".

Once the Steamworks settings are published, the editing application will be able to publish content to the base application's workshop.