How to Upload Workshop Content to Steam

Introduction

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

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 employ and how to brand the best out of the tools provided past Steam please meet 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 so be able to scan, sort, rate, and subscribe to items they wish to add together 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 telephone call ISteamUGC::GetItemInstallInfo to get the installed location and read the information directly from that binder. That new content would so be recognized by the game in whatsoever capacity makes sense for your game and the content created.

Steam Workshop Types, Monetization, & Best Practices

For more data and definitions of the various types of Workshop integration you can utilise and how to make the all-time 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 annotate on the content visible through the customs. By default, applications are not enabled to exist 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 country of the workshop through the post-obit steps:

Scan to the application landing folio on the Steamworks website
Click Edit Steamworks Settings
From the Workshop Tab, select Full general
On the right-hand side of the page, find the Visibility State section.
Use the radio buttons to select the desired level of visibility which tin can include Developers But, Developers & Testers, Customers & Developers and Everyone.
From the Publish tab, click Prepare for Publishing
Click Publish to Steam and complete the process to publish the modify.

Note: To alter the visibility state to Everyone, the Workshop checklist must be consummate which includes branding, title, description and at least i particular 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 detail 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:

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

Enabling ISteamUGC for a Game or Application

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

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

Navigate to the Steam Cloud Settings page in the App Admin console.
Set the Byte quota per user and Number of files allowed per user to appropriate values for preview prototype storage
Click Save
From the Publish tab, click Fix for Publishing
Click Publish to Steam and consummate the process to publish the alter.

Enabling the ISteamUGC API can be accomplished with the post-obit steps:

Navigate to the Steam Workshop Configuration page in the App Admin panel.
Find the Additional Configuration Options section.
Bank check Enable ISteamUGC for file transfer.
Click Salve.
From the Publish tab, click Gear up for Publishing.
Click Publish to Steam and complete the process to publish the alter.

In one case these settings are in place workshop content can exist 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 menstruation chart beneath.

Creating a Workshop Item

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 cosmos tool if that is a divide App ID.
- EWorkshopFileType is an enumeration blazon that defines how the shared file will be shared with the community. The valid values are:
  - k_EWorkshopFileTypeCommunity - This file blazon is used to depict files that will be uploaded past users and made bachelor to download past anyone in the community. Mutual usage of this would be to share user created mods.
  - k_EWorkshopFileTypeMicrotransaction - This file type is used to draw files that are uploaded by users, but intended only for the game to consider calculation as official content. These files will not exist downloaded past users through the Workshop, but volition exist viewable by the community to rate.
    This is the implementation that Squad Fortress 2 uses.
Register a call event handler for CreateItemResult_t
First check the m_eResult to ensure that the item was created successfully.
When the telephone call event handler is executed, read the m_nPublishedFileId value and shop for future updates to the workshop item (east.g. in a project file associated with the creation tool).
The m_bUserNeedsToAcceptWorkshopLegalAgreement variable should likewise be checked and if information technology'due south true, the user should be redirected to have the legal agreement. Come across the Workshop Legal Agreement section for more details.

Uploading a Workshop Detail

One time a workshop particular has been created and a PublishedFileId_t value has been returned, the content of the workshop particular tin be populated and uploaded to the Steam Workshop.
An particular update begins with a call to ISteamUGC::StartItemUpdate
Using the UGCUpdateHandle_t that is returned from ISteamUGC::StartItemUpdate, calls can be made to update the Title, Description, Visibility, Tags, Detail Content and Particular 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 particular.
- ISteamUGC::SetItemUpdateLanguage - Sets the linguistic communication of the title and clarification 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 bodily content.
- ISteamUGC::SetItemVisibility - Sets the visibility of an detail.
- ISteamUGC::SetItemTags - Sets arbitrary developer specified tags on an item.
- ISteamUGC::AddItemKeyValueTag - Adds a key-value tag pair to an item. Keys tin map to multiple different values (1-to-many relationship).
- ISteamUGC::RemoveItemKeyValueTags - Removes an existing cardinal value tag from an detail.
- ISteamUGC::SetItemContent - Sets the folder that volition be stored as the content for an detail.
- ISteamUGC::SetItemPreview -Sets the chief preview image for the detail.
Once the update calls have been completed, calling ISteamUGC::SubmitItemUpdate will initiate the upload process to the Steam Workshop.
- Register a telephone call effect handler for SubmitItemUpdateResult_t
- When the call result handler is executed, check the m_eResult to confirm the upload completed successfully.
- Notation: There is no method to cancel the item update and upload once information technology's been called.
If desired, the progress of the upload can exist tracked using ISteamUGC::GetItemUpdateProgress
- EItemUpdateStatus defines the upload and update progress.
- punBytesProcessed and punBytesTotal can exist used to provide input for a user interface control such as a progress bar to signal progress of the upload.
- punBytesTotal may update during the upload process based upon the stage of the item update.
In the same way as Creating a Workshop Particular, confirm the user has accustomed the legal agreement. This is necessary in case where the user didn't initially create the particular but is editing an existing particular.

Additional Notes

Workshop items were previously designated as unmarried files. With ISteamUGC, a workshop item is a representation of a binder of files.
If a workshop detail requires additional metadata for use by the consuming application, y'all 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 salvage this metadata to a file within the workshop particular folder, which of grade y'all can notwithstanding do.

Consuming Content

Consuming workshop content falls into 2 categories, Detail 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 discover and subscribe to items regularly on the workshop site.

Nevertheless, 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 every bit soon equally possible.
ISteamUGC::UnsubscribeItem - Unsubscribe from a workshop item. This will effect in the item being removed subsequently the game quits.

Two boosted methods exist for enumerating through a user'due south 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 electric current game.

Receiving Notifications for External Subscription Actions

In-game notifications tin can exist received when a user has subscribed or unsubscribed from a file through whatsoever mechanism (e.k. ISteamUGC, Steam Workshop Website):

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

Detail Installation

Once Item Subscription information is known, the remaining consumption methods can be utilized. These methods provide information dorsum to the game most 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:

When the Steam Client indicates a game or application is to launch, all app depots that have been updated will be downloaded and installed.
Any existing installed workshop items are updated if needed
Game or application then launches
Newly subscribed workshop items that are not downloaded will then download and be installed in the background.
- Subscribed files volition be downloaded to the customer in the guild they were subscribed in.
- The Steam download page will show workshop detail downloads with a specific imprint to signal a workshop item download is occurring.

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

Every bit the game volition showtime before newly subscribed content is downloaded and installed, the remaining consumption methods be to aid in monitoring and managing the install progress. They can too exist used when items are subscribed in-game to provide condition of installation in real time.

Status of a Workshop Detail

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

Download Progress of a Workshop Detail

ISteamUGC::GetItemDownloadInfo - Become info about a pending download of a workshop detail that has k_EItemStateNeedsUpdate set up.

Initiate or Increase the Priority of Downloading a Workshop Item

ISteamUGC::DownloadItem
- Set bHighPriority to true to interruption whatever existing in-progress downloads and immediately brainstorm downloading this workshop item.
- If the render value is true then register and wait for the callback ISteamUGC::DownloadItemResult_t earlier calling ISteamUGC::GetItemInstallInfo or accessing the workshop item on disk.
- If the user is not subscribed to the item (due east.g. a Game Server using anonymous login), the workshop item volition exist 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 admission the workshop detail on disk until the callback ISteamUGC::DownloadItemResult_t is called.
- This method only works with ISteamUGC created workshop items. It volition not work with legacy ISteamRemoteStorage workshop items.
- The ISteamUGC::DownloadItemResult_t callback struct contains the awarding ID (m_unAppID) associated with the workshop detail. It should be compared confronting the running awarding ID as the handler will exist chosen for all item downloads regardless of the running awarding.

Retrieving information about the local copy of the Workshop Detail

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

Notification when a Workshop Particular is Installed or Updated

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.).

Register a call effect handler for SteamUGCQueryCompleted_t.
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 utilize this to listing the UGC the user is subscribed to amongst other things.
- ISteamUGC::CreateQueryAllUGCRequest - Query for all matching UGC. Y'all tin employ this to list all of the available UGC for your app.
- ISteamUGC::CreateQueryUGCDetailsRequest - Query for the details of specific workshop items.
Customize the query as advisable by calling the selection setting methods:
- When querying for User UGC
  - ISteamUGC::SetCloudFileNameFilter - Sets to but render 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 i or more than matching tag, or if all tags demand to match on a awaiting UGC Query.
  - ISteamUGC::SetSearchText - Sets a string to that items need to match in either the title or the clarification on a awaiting UGC Query.
  - ISteamUGC::SetRankedByTrendDays - Sets whether the order of the results volition be updated based on the rank of items over a number of days on a pending UGC Query.
- When querying for either blazon 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 volition only return UGC without the specified tag.
  - ISteamUGC::AddRequiredKeyValueTag - Adds a required fundamental-value tag to a pending UGC Query. This will only return workshop items that have a cardinal = [param]pKey[/param] and a value = [param]pValue[/param].
  - ISteamUGC::SetReturnOnlyIDs - Sets whether to just 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 but desire to get the IDs of the items a user has in their favorites list.)
  - ISteamUGC::SetReturnKeyValueTags - Sets whether to return any cardinal-value tags for the items on a pending UGC Query.
  - ISteamUGC::SetReturnLongDescription - Sets whether to return the full description for the items on a awaiting 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 render the IDs of the child items of the items on a pending UGC Query.
  - ISteamUGC::SetReturnAdditionalPreviews - Sets whether to render whatsoever additional images/videos attached to the items on a pending UGC Query.
  - ISteamUGC::SetReturnTotalOnly - Sets whether to merely render the full number of matching items on a pending UGC Query. -- The bodily items volition not be returned when ISteamUGC::SteamUGCQueryCompleted_t is called.
  - ISteamUGC::SetLanguage - Sets the language to return the title and clarification 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 fourth dimension on a pending UGC Query.
Send the query to Steam using ISteamUGC::SendQueryUGCRequest which will invoke the ISteamUGC::SteamUGCQueryCompleted_t telephone call event handler registered in step 1.
In the call result handler for ISteamUGC::SteamUGCQueryCompleted_t, call ISteamUGC::GetQueryUGCResult to retrieve the details for each item returned.
Y'all can likewise call these functions to retrieve additional information for each item (some of this data is not returned by default, and then you demand to configure your query accordingly):
- ISteamUGC::GetQueryUGCPreviewURL - Retrieve the URL to the preview image of an individual workshop particular subsequently receiving a querying UGC call consequence.
- ISteamUGC::GetQueryUGCMetadata - Call up the developer fix metadata of an individual workshop item afterward receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCChildren - Retrieve the ids of any child items of an individual workshop particular after receiving a querying UGC call event.
- 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 effect.
- ISteamUGC::GetQueryUGCNumKeyValueTags and ISteamUGC::GetQueryUGCKeyValueTag - Retrieve the details of a key-value tag associated with an individual workshop detail after receiving a querying UGC call effect.
Call ISteamUGC::ReleaseQueryUGCRequest to gratuitous upwardly whatsoever memory allocated while querying or retrieving the results.

Paging Results

Up to fifty results volition exist returned from each query. Paging through more results can be achieved past creating a query that increments the unPage parameter (which should kickoff at i).

Playtime Tracking

To track the playtime of Workshop items simply call ISteamUGC::StartPlaytimeTracking with the ids of the items you want to rail. So when the items are removed from play telephone call ISteamUGC::StopPlaytimeTracking with the ids you want to finish tracking or call ISteamUGC::StopPlaytimeTrackingForAllItems to terminate tracking playtime for all items at in one case.
When your app shuts downward, playtime tracking will automatically stop.

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

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

Deleting Workshop Item Content

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

Steamworks Example – SpaceWar Integration

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

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

Workshop Legal Agreement

Workshop items will be hidden past default until the correspondent agrees to the Steam Workshop Legal Agreement. In society to go far easy for the contributor to make the detail publicly visible, please do the following.

Include text next to the push button that submits an item to the workshop, something to the outcome of: "By submitting this item, you agree to the workshop terms of service" (including the link)
Afterward a user submits an particular, 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 particular id.

This has the benefit of directing the author to the workshop folio so that they can run into the item and configure information technology further if necessary and will arrive easy for the user to read and accept the Steam Workshop Legal Agreement.

Web API

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

Defended 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 ready by the server operator. Then call ISteamUGC::DownloadItem to recall a temporary copy of the workshop item.
A telephone call can then be made to ISteamUGC::GetItemInstallInfo to recollect information to locate and utilize 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 detail using steamcmd.exe a VDF file must first be created. The VDF is a plain text file that should contain the post-obit keys.

"workshopitem" { "appid" "480" "publishedfileid" "5674" "contentfolder" "D:\\Content\\workshopitem" "previewfile" "D:\\Content\\preview.jpg" "visibility" "0" "championship" "Squad Fortress Green Hat" "description" "A green chapeau for Team Fortress" "changenote" "Version ane.2" }

Notes:

The keys map to the various ISteamUGC::SetItem[...] methods. Encounter 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.

One time the VDF has been created, steamcmd.exe tin be run with the workshop_build_item <build config filename> file parameter. For example:

steamcmd.exe +login myLoginName myPassword +workshop_build_item workshop_green_hat.vdf +quit

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 fashion, 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 comprise EResult variables that tin be checked.

Oftentimes Asked Questions

Q: Can a separate awarding publish content to my game'due south Workshop?

Yep. A divide awarding for editing or publishing tools tin can be configured with base application's workshop to accept content from that editing application.

To configure this, get to the Workshop Configuration section for the base application and curlicue to the bottom of the page. Enter the separate awarding'southward App ID in the field under "App Publish Permissions" and hit "Add together".

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

searleblers1987.blogspot.com

Source: https://partner.steamgames.com/doc/features/workshop/implementation