How to Upload a Gif as a Workshop Item

Introduction

Steam Workshop is a organization of back-end storage and front end-terminate web pages that make it piece of cake to shop, 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 delight see the Steam Workshop Overview before getting started integrating the steam workshop with your game.

In a typical prepare-up, customers of your game would apply tools provided by y'all with buy of your game to create modifications or entirely new content. Those customers would so submit that content through a grade congenital into your tool to the Steam Workshop. Other customers would then 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 Community. Those items would then download through Steam. If y'all've registered for the ISteamUGC::ItemInstalled_t callback within your game, you can so call ISteamUGC::GetItemInstallInfo to get the installed location and read the data straight from that binder. That new content would so 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 data and definitions of the various types of Workshop integration you tin can apply and how to make the best out of the tools provided by Steam, please meet 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 non 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:

Browse to the awarding landing folio on the Steamworks website
Click Edit Steamworks Settings
From the Workshop Tab, select General
On the right-hand side of the page, observe the Visibility State section.
Use the radio buttons to select the desired level of visibility which can include Developers Only, 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 change.

Note: To modify the visibility country to Everyone, the Workshop checklist must be complete which includes branding, championship, 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 institute in the Steamworks SDK. The methods exposed provide a way to share workshop item content which can then exist discovered through the Steam Workshop or an in-app experience.

The Workshop API must exist 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 can be uploaded to the Steamworks backend there are 2 configuration settings that must be fabricated, Configuring Steam Deject Quotas and Enabling the ISteamUGC API.

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

Navigate to the Steam Cloud Settings page in the App Admin panel.
Set the Byte quota per user and Number of files allowed per user to appropriate values for preview image storage
Click Relieve
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 exist accomplished with the following steps:

Navigate to the Steam Workshop Configuration page in the App Admin panel.
Find the Boosted Configuration Options section.
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 change.

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

Creating and Uploading Content

The procedure of creating and uploading workshop content is a uncomplicated and repeatable procedure equally shown in the menstruum chart below.

Creating a Workshop Particular

All workshop items begin their being with a telephone 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 separate 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 draw files that will be uploaded by users and made bachelor to download by anyone in the customs. Common usage of this would exist to share user created mods.
  - k_EWorkshopFileTypeMicrotransaction - This file type is used to describe files that are uploaded by users, merely intended only for the game to consider adding as official content. These files will not be downloaded past users through the Workshop, but will be viewable by the community to charge per unit.
    This is the implementation that Team Fortress two uses.
Annals a phone call consequence handler for CreateItemResult_t
First cheque the m_eResult to ensure that the particular was created successfully.
When the call issue handler is executed, read the m_nPublishedFileId value and store for future updates to the workshop particular (east.g. in a project file associated with the cosmos tool).
The m_bUserNeedsToAcceptWorkshopLegalAgreement variable should also exist checked and if it's true, the user should exist redirected to accept the legal agreement. See the Workshop Legal Understanding department for more details.

Uploading a Workshop Item

One time 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.
An item update begins with a telephone 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, 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 linguistic communication of the title and description that will exist set up in this particular 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 detail. 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 volition exist stored as the content for an item.
- ISteamUGC::SetItemPreview -Sets the primary preview image for the item.
Once the update calls accept been completed, calling ISteamUGC::SubmitItemUpdate will initiate the upload procedure to the Steam Workshop.
- Register a call result handler for SubmitItemUpdateResult_t
- When the call event handler is executed, check the m_eResult to confirm the upload completed successfully.
- Note: In that location is no method to abolish the particular update and upload in one case it'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 indicate progress of the upload.
- punBytesTotal may update during the upload process based upon the stage of the detail update.
In the same way as Creating a Workshop Detail, confirm the user has accepted the legal agreement. This is necessary in instance 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 detail is a representation of a folder of files.
If a workshop particular requires boosted metadata for use by the consuming awarding, you can adhere metadata to your item using the ISteamUGC::SetItemMetadata call. This metadata can be returned in queries without having to download and install the particular content.
Previously we suggested that yous salvage this metadata to a file inside the workshop detail folder, which of form you lot tin 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 detail subscription management.

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

Ii additional methods be for enumerating through a user'due south 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 be received when a user has subscribed or unsubscribed from a file through whatsoever mechanism (e.g. ISteamUGC, Steam Workshop Website):

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

Particular Installation

In one case Detail Subscription information is known, the remaining consumption methods can be utilized. These methods provide data back to the game almost the land 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 Customer 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 and then launches
Newly subscribed workshop items that are not downloaded will then download and be installed in the groundwork.
- Subscribed files will exist downloaded to the client in the order they were subscribed in.
- The Steam download page will show workshop item downloads with a specific imprint to indicate a workshop particular download is occurring.

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

Every bit the game will first before newly subscribed content is downloaded and installed, the remaining consumption methods exist to assist in monitoring and managing the install progress. They can also be used when items are subscribed in-game to provide condition of installation in real fourth dimension.

Status of a Workshop Item

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

Download Progress of a Workshop Detail

ISteamUGC::GetItemDownloadInfo - Go info about a pending download of a workshop detail that has k_EItemStateNeedsUpdate fix.

Initiate or Increase the Priority of Downloading a Workshop Item

ISteamUGC::DownloadItem
- Set bHighPriority to true to break whatsoever existing in-progress downloads and immediately begin downloading this workshop item.
- If the return value is true so register and await for the callback ISteamUGC::DownloadItemResult_t before calling ISteamUGC::GetItemInstallInfo or accessing the workshop item on deejay.
- If the user is not subscribed to the detail (east.one thousand. a Game Server using anonymous login), the workshop item will be downloaded and buried temporarily.
- If the workshop item has an ISteamUGC::EItemState of k_EItemStateNeedsUpdate, ISteamUGC::DownloadItem can be chosen to initiate the update. Exercise not access the workshop item on deejay until the callback ISteamUGC::DownloadItemResult_t is chosen.
- This method merely works with ISteamUGC created workshop items. It will non 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 exist compared against the running application ID every bit the handler will exist chosen for all item downloads regardless of the running awarding.

Retrieving information virtually the local copy of the Workshop Item

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

Notification when a Workshop Item is Installed or Updated

Querying Content

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

Annals a 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 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. Y'all can use this to list all of the available UGC for your app.
- ISteamUGC::CreateQueryUGCDetailsRequest - Query for the details of specific workshop items.
Customize the query equally appropriate by calling the selection 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 will exist 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 exist 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 awaiting UGC Query. This will 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 accept 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 simply want to become 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 awaiting UGC Query.
  - ISteamUGC::SetReturnLongDescription - Sets whether to return the full clarification for the items on a pending UGC Query.
  - ISteamUGC::SetReturnMetadata - Sets whether to return the programmer specified metadata for the items on a pending UGC Query.
  - ISteamUGC::SetReturnChildren - Sets whether to return the IDs of the kid items of the items on a pending UGC Query.
  - ISteamUGC::SetReturnAdditionalPreviews - Sets whether to return any boosted images/videos attached to the items on a pending UGC Query.
  - ISteamUGC::SetReturnTotalOnly - Sets whether to just return the total number of matching items on a pending UGC Query. -- The actual items will non exist 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 be will exist returned from the cache for the specific period of time on a awaiting UGC Query.
Ship the query to Steam using ISteamUGC::SendQueryUGCRequest which volition invoke the ISteamUGC::SteamUGCQueryCompleted_t call result handler registered in step 1.
In the call event handler for ISteamUGC::SteamUGCQueryCompleted_t, call ISteamUGC::GetQueryUGCResult to recall the details for each particular returned.
Y'all can likewise call these functions to retrieve additional information for each item (some of this information is not returned by default, then you need to configure your query appropriately):
- ISteamUGC::GetQueryUGCPreviewURL - Call up the URL to the preview image of an individual workshop item afterwards receiving a querying UGC call upshot.
- ISteamUGC::GetQueryUGCMetadata - Recollect the programmer prepare metadata of an individual workshop item after receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCChildren - Think the ids of any child items of an private workshop particular after receiving a querying UGC telephone call result.
- ISteamUGC::GetQueryUGCStatistic - Retrieve various statistics of an individual workshop item afterwards receiving a querying UGC call result.
- ISteamUGC::GetQueryUGCNumAdditionalPreviews and ISteamUGC::GetQueryUGCAdditionalPreview - Retrieve the details of an boosted preview associated with an individual workshop item after receiving a querying UGC telephone call result.
- ISteamUGC::GetQueryUGCNumKeyValueTags and ISteamUGC::GetQueryUGCKeyValueTag - Retrieve the details of a key-value tag associated with an private workshop detail after receiving a querying UGC call issue.
Call ISteamUGC::ReleaseQueryUGCRequest to free upward whatever 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 kickoff at 1).

Playtime Tracking

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

Yous volition also exist able to sort items by diverse 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 "tendency" period descending (set with ISteamUGC::SetRankedByTrendDays)
k_EUGCQuery_RankedByTotalPlaytime - Sort past full lifetime playtime descending.
k_EUGCQuery_RankedByAveragePlaytimeTrend - Sort by average playtime in the "trend" period descending (fix with ISteamUGC::SetRankedByTrendDays)
k_EUGCQuery_RankedByLifetimeAveragePlaytime - Sort by lifetime average playtime descending
k_EUGCQuery_RankedByPlaytimeSessionsTrend - Sort by number of play sessions in the "trend" menstruum 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. Delight notation that this does not prompt the user and cannot exist undone.

Steamworks Example – SpaceWar Integration

The Steamworks API Example Awarding (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 data 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 Understanding

Workshop items will be hidden by default until the contributor agrees to the Steam Workshop Legal Understanding. In order to brand information technology like shooting fish in a barrel for the contributor to make the item publicly visible, please exercise the post-obit.

Include text adjacent to the push button that submits an particular to the workshop, something to the result of: "By submitting this particular, you agree to the workshop terms of service" (including the link)
Later on a user submits an particular, open a browser window to the Steam Workshop folio for that item by calling ISteamFriends::ActivateGameOverlayToWebPage with pchURL fix 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 and then that they can see the item and configure it farther if necessary and volition go far easy for the user to read and take 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.

Dedicated Game Servers

Game servers can besides download and install items.

The Game Server will need to know the PublishedFileId_t to asking a workshop item, this could be supplied by the game clients or ready by the server operator. And so call ISteamUGC::DownloadItem to retrieve a temporary copy of the workshop item.
A call can then be made to ISteamUGC::GetItemInstallInfo to think data to locate and utilize the workshop item.
See the Particular Installation department above for more information on these API methods.

SteamCmd Integration

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

To create a new Steam Workshop item using steamcmd.exe a VDF file must first exist created. The VDF is a plain 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" "Team Fortress Light-green Chapeau" "description" "A green hat for Squad Fortress" "changenote" "Version 1.ii" }

Notes:

The keys map to the various ISteamUGC::SetItem[...] methods. Meet the documentation above for more details.
The values shown are examples only and should be updated appropriately.
To create a new item, appid must exist 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 exist included in the VDF if the primal should be updated.

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

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

If the control is successful, the publishedfileid value in the VDF will exist automatically updated to contain the ID of the workshop item. In this way, subsequent calls with steamcmd.exe for the same VDF will event in an update rather than creation of a new detail.

Errors and Logging

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

Steam\logs\Workshop_log.txt is a log for all transfers that occur during workshop detail downloading
and installation.
Steam\workshopbuilds\depot_build_<appid>.log is a log for all deportment 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: Tin can a separate application publish content to my game's Workshop?

Yep. A split up application for editing or publishing tools can be configured with base application's workshop to have content from that editing awarding.

To configure this, go to the Workshop Configuration section for the base application and whorl to the bottom of the page. Enter the separate application'southward App ID in the field nether "App Publish Permissions" and hitting "Add".

One time the Steamworks settings are published, the editing application will be able to publish content to the base of operations awarding's workshop.

blankwherrigh.blogspot.com

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