How to Upload an Item to Steam Workshop

abril 12, 2022 Enviar um comentário

Introduction

Steam Workshop is a organisation of back-finish storage and front-end spider web pages that brand information technology easy to store, organize, sort, rate, and download content for your game or application.

This folio 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 brand the best out of the tools provided past Steam please see the Steam Workshop Overview before getting started integrating the steam workshop with your game.

In a typical fix-upward, customers of your game would use tools provided by you with buy of your game to create modifications or entirely new content. Those customers would so submit that content through a form congenital into your tool to the Steam Workshop. Other customers would and so be able to scan, sort, rate, and subscribe to items they wish to add to their game by going to the Steam Workshop in the Steam Customs. Those items would and then download through Steam. If you lot've registered for the ISteamUGC::ItemInstalled_t callback within your game, you can and so call ISteamUGC::GetItemInstallInfo to get the installed location and read the information straight 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, & All-time Practices

For more information and definitions of the various types of Workshop integration yous tin utilize 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 community. By default, applications are not enabled to be publicly visible in the Workshop. This prevents content not intended to exist shared through the Steam Workshop portal from being visible unless the workshop is set up to public.
Set the visibility state of the workshop through the following steps:

Browse 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 department.
Apply the radio buttons to select the desired level of visibility which can include Developers Only, Developers & Testers, Customers & Developers and Anybody.
From the Publish tab, click Set up for Publishing
Click Publish to Steam and complete the procedure to publish the modify.

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

Tech Overview

The process to share and eat User Generated Content is by using the ISteamUGC API which tin can exist found in the Steamworks SDK. The methods exposed provide a way to share workshop particular content which tin 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 instance:

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

Enabling ISteamUGC for a Game or Awarding

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

The Steam Deject characteristic is used to store the preview images associated to workshop items. The Steam Deject Quota tin be configured with the following steps:

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

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

Navigate to the Steam Workshop Configuration folio in the App Admin console.
Find the Additional Configuration Options department.
Check Enable ISteamUGC for file transfer.
Click Save.
From the Publish tab, click Prepare for Publishing.
Click Publish to Steam and complete the procedure to publish the alter.

Once 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 every bit shown in the flow chart below.

Creating a Workshop Detail

All workshop items begin their beingness with a call to ISteamUGC::CreateItem
- The nConsumerAppId variable should contain the App ID for the game or application. Do not laissez passer the App ID of the workshop item creation tool if that is a dissever 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 volition 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 depict files that are uploaded by users, only intended only for the game to consider calculation every bit official content. These files will non be downloaded by users through the Workshop, but will be viewable past the customs to rate.
    This is the implementation that Team Fortress two uses.
Register a call result handler for CreateItemResult_t
First check the m_eResult to ensure that the item was created successfully.
When the call result handler is executed, read the m_nPublishedFileId value and store for future updates to the workshop detail (e.g. in a project file associated with the creation tool).
The m_bUserNeedsToAcceptWorkshopLegalAgreement variable should also be checked and if it's true, the user should exist redirected to take the legal agreement. See the Workshop Legal Understanding department for more details.

Uploading a Workshop Detail

Once a workshop detail 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.
An detail update begins with a telephone call to ISteamUGC::StartItemUpdate
Using the UGCUpdateHandle_t that is returned from ISteamUGC::StartItemUpdate, calls tin can exist fabricated to update the Title, Clarification, Visibility, Tags, Detail Content and Particular Preview Paradigm through the various ISteamUGC::SetItem[...] methods.
- ISteamUGC::SetItemTitle - Sets a new championship for an item.
- ISteamUGC::SetItemDescription - Sets a new clarification for an item.
- ISteamUGC::SetItemUpdateLanguage - Sets the language of the title and description that will be fix 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 detail.
- ISteamUGC::SetItemTags - Sets arbitrary programmer specified tags on an detail.
- ISteamUGC::AddItemKeyValueTag - Adds a cardinal-value tag pair to an particular. Keys can map to multiple dissimilar values (1-to-many relationship).
- ISteamUGC::RemoveItemKeyValueTags - Removes an existing key value tag from an particular.
- ISteamUGC::SetItemContent - Sets the folder that will be stored as the content for an detail.
- ISteamUGC::SetItemPreview -Sets the primary preview paradigm for the item.
Once the update calls accept been completed, calling ISteamUGC::SubmitItemUpdate volition initiate the upload process to the Steam Workshop.
- Register a telephone call result handler for SubmitItemUpdateResult_t
- When the call issue handler is executed, bank check the m_eResult to confirm the upload completed successfully.
- Annotation: There is no method to cancel the item update and upload one time information technology's been called.
If desired, the progress of the upload tin 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 equally a progress bar to indicate progress of the upload.
- punBytesTotal may update during the upload process based upon the stage of the item update.
In the aforementioned way as Creating a Workshop Item, confirm the user has accepted the legal understanding. This is necessary in case where the user didn't initially create the item merely is editing an existing item.

Additional Notes

Workshop items were previously designated as single files. With ISteamUGC, a workshop particular is a representation of a folder of files.
If a workshop item requires boosted metadata for apply by the consuming awarding, you can attach metadata to your item using the ISteamUGC::SetItemMetadata call. This metadata can exist returned in queries without having to download and install the item content.
Previously we suggested that you relieve this metadata to a file inside the workshop detail folder, which of course you tin can nonetheless exercise.

Consuming Content

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

Item Subscription

The majority of subscriptions to a workshop item volition 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.

Even so, ISteamUGC provides 2 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 shortly as possible.
ISteamUGC::UnsubscribeItem - Unsubscribe from a workshop item. This volition consequence in the particular being removed afterwards the game quits.

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

ISteamUGC::GetNumSubscribedItems - Gets the full number of items the electric 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 exist received when a user has subscribed or unsubscribed from a file through any mechanism (e.thou. 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 access the information about the workshop item.
The structs also contain the application ID (m_unAppID) associated with the workshop item. It should exist compared against the running application ID as the handler volition exist called for all particular subscriptions regardless of the running application.

Item Installation

In one case Item Subscription information is known, the remaining consumption methods tin can be utilized. These methods provide information dorsum to the game about the country 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 accept 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 volition then download and be installed in the background.
- Subscribed files volition exist downloaded to the customer in the lodge they were subscribed in.
- The Steam download folio volition bear witness workshop particular 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 too cause workshop items to exist downloaded.

Every bit the game will offset earlier newly subscribed content is downloaded and installed, the remaining consumption methods exist to aid in monitoring and managing the install progress. They tin can also exist used when items are subscribed in-game to provide status of installation in existent fourth dimension.

Status of a Workshop Detail

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

Download Progress of a Workshop Item

ISteamUGC::GetItemDownloadInfo - Get info virtually a pending download of a workshop item that has k_EItemStateNeedsUpdate prepare.

Initiate or Increase the Priority of Downloading a Workshop Item

ISteamUGC::DownloadItem
- Set bHighPriority to truthful to pause any existing in-progress downloads and immediately brainstorm downloading this workshop detail.
- If the render value is true then annals and expect for the callback ISteamUGC::DownloadItemResult_t before calling ISteamUGC::GetItemInstallInfo or accessing the workshop detail on disk.
- If the user is not subscribed to the item (east.g. a Game Server using anonymous login), the workshop item will be downloaded and cached temporarily.
- If the workshop detail has an ISteamUGC::EItemState of k_EItemStateNeedsUpdate, ISteamUGC::DownloadItem tin can exist chosen to initiate the update. Do not access the workshop particular 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. Information technology should be compared against the running application ID equally the handler volition exist chosen for all particular downloads regardless of the running application.

Retrieving information nigh the local copy of the Workshop Particular

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

Notification when a Workshop Item is Installed or Updated

Annals a callback handler for ISteamUGC::ItemInstalled_t.

Querying Content

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

Annals a telephone call result 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 accept ids for.
- ISteamUGC::CreateQueryUserUGCRequest - Query UGC associated with a user. You lot can use this to list the UGC the user is subscribed to amongst other things.
- ISteamUGC::CreateQueryAllUGCRequest - Query for all matching UGC. You tin use this to listing all of the bachelor UGC for your app.
- ISteamUGC::CreateQueryUGCDetailsRequest - Query for the details of specific workshop items.
Customize the query every bit advisable past calling the option setting methods:
- When querying for User UGC
  - ISteamUGC::SetCloudFileNameFilter - Sets to only return items that take a specific filename on a pending UGC Query.
- When querying for All UGC
  - ISteamUGC::SetMatchAnyTag - Sets whether workshop items volition be returned if they have i or more matching tag, or if all tags need to match on a awaiting UGC Query.
  - ISteamUGC::SetSearchText - Sets a cord 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 volition 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 key-value tag to a awaiting UGC Query. This will only return workshop items that take a key = [param]pKey[/param] and a value = [param]pValue[/param].
  - ISteamUGC::SetReturnOnlyIDs - Sets whether to only render IDs instead of all the details on a pending UGC Query. This is useful for when you don't demand all the information (e.k. you lot just desire 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 total 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 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 render the full number of matching items on a pending UGC Query. -- The actual items will non be returned when ISteamUGC::SteamUGCQueryCompleted_t is called.
  - ISteamUGC::SetLanguage - Sets the language to render the title and description in for the items on a pending UGC Query.
  - ISteamUGC::SetAllowCachedResponse - Sets whether results to exist will be returned from the cache for the specific period of time on a pending UGC Query.
Send the query to Steam using ISteamUGC::SendQueryUGCRequest which volition invoke the ISteamUGC::SteamUGCQueryCompleted_t telephone call result handler registered in stride 1.
In the call result handler for ISteamUGC::SteamUGCQueryCompleted_t, call ISteamUGC::GetQueryUGCResult to call up the details for each item returned.
You can also call these functions to retrieve additional information for each item (some of this data is not returned by default, so you lot need to configure your query appropriately):
- ISteamUGC::GetQueryUGCPreviewURL - Retrieve the URL to the preview prototype of an individual workshop item after receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCMetadata - Recall the developer set metadata of an private workshop item after receiving a querying UGC phone call outcome.
- ISteamUGC::GetQueryUGCChildren - Retrieve the ids of any kid items of an individual workshop item after receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCStatistic - Call back various statistics of an private workshop item afterward receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCNumAdditionalPreviews and ISteamUGC::GetQueryUGCAdditionalPreview - Retrieve the details of an additional preview associated with an individual workshop particular after receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCNumKeyValueTags and ISteamUGC::GetQueryUGCKeyValueTag - Call back the details of a key-value tag associated with an individual workshop item after receiving a querying UGC call upshot.
Call ISteamUGC::ReleaseQueryUGCRequest to complimentary upwards any memory allocated while querying or retrieving the results.

Paging Results

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

Playtime Tracking

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

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

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

Deleting Workshop Item Content

To delete a Workshop particular, yous can call ISteamUGC::DeleteItem. Delight notation that this does not prompt the user and cannot be undone.

Steamworks Instance – 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 every bit 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 correspondent agrees to the Steam Workshop Legal Agreement. In social club to make it like shooting fish in a barrel for the contributor to make the item publicly visible, please do the following.

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

This has the benefit of directing the writer to the workshop page so that they tin see the item and configure it further if necessary and will get in piece of cake for the user to read and have the Steam Workshop Legal Agreement.

Web API

In improver 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.

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 gear up by the server operator. Then call ISteamUGC::DownloadItem to retrieve a temporary copy of the workshop item.
A telephone call can then exist made to ISteamUGC::GetItemInstallInfo to retrieve information to locate and use the workshop item.
Run across the Item Installation section higher up for more information on these API methods.

SteamCmd Integration

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

To create a new Steam Workshop item using steamcmd.exe a VDF file must starting time exist created. The VDF is a evidently text file that should contain the following keys.

"workshopitem" { "appid" "480" "publishedfileid" "5674" "contentfolder" "D:\\Content\\workshopitem" "previewfile" "D:\\Content\\preview.jpg" "visibility" "0" "title" "Squad Fortress Green Hat" "clarification" "A green hat for Team Fortress" "changenote" "Version 1.ii" }

Notes:

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

Once the VDF has been created, steamcmd.exe tin can exist 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 control is successful, the publishedfileid value in the VDF volition 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 cosmos of a new detail.

Errors and Logging

The majority of ISteamUGC methods render boolean values. For additional data 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 deportment during the upload and update of a workshop detail.
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?

Yep. A split application for editing or publishing tools can be configured with base of operations application'southward 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 awarding'due south App ID in the field nether "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 awarding's workshop.

shoffnerbellordes.blogspot.com

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

Shoffner Bellordes