User Generated Content (Workshop)

Introduction

Available in the Steamworks Complete asset.
The User Generate Content (UGC) API from Valve is used for a number of features including Leaderboard Details. This section of the Heathen Knowledge Base however deals with the use of UGC for Workshop files.
The typical use case is that you enable your users and or you yourself create workshop files (aka mods) and upload them to Valve's Workshop. These can then be browsed for and subscribed to by players. The system will then download the content that belongs to the subscribed mods and make that available to your game.

Concepts

Item File

This is not a single "file" such as a word.doc or folder.zip, instead this is an ID that represents a collection of content on the Steam UGC system and can be browsed for via the Steam Workshop interface. A given Workshop "file" may contain many files, it will have at least a description, name and preview image.

Content Folder

When you create a new UGC item e.g. Workshop entry, you provide several bits of information including a "Content Folder Path". The files in this folder path will be collected by the Steam client, compressed and uploaded to Steam. You should not include compressed files such as zip or rar.

Subscription

As with DLC, Apps and Games, when Valve says you are "subscribed" to a thing it means that you have access to it. In the case of Workshop this means its been selected by the user and is or will be downloaded to the user's machine and keep up-to date.

Browse the Workshop

While the typical use case is that the user would browse for items in the Steam Client, and this would be Heathen's recommendation as well, the Steam Client's UI is going to be duty built for the task where your game's UI is not.
It is however possible to browse the workshop in game and Heathen's Steamworks SDK provides a number of tools to help you with this.
Heathen Engineering has created a component to simplify the task of searching and browsing Steam User Generated Content items. This component can be used to create a query and cycle it over pages.
Steam UGC Queries are page based queries that is Steam will return a subset of the matching records aka pages. To read all available records you would need to iterate over all the available pages updating the query to match the required page each time.

UGC Query

The UGC Query Manager uses the UGC Query object to perform all of its actions. You can use these same tools to create a completely bespoke (custom) browser experience.

How To

In Game Workshop Browser

How you set up the UI is up to you, the UGC Query Manager manages the query and its results for you, its up to you to display those to the user how you see fit.

Step 1

The first thing you will want to do is add a UGC Query Manager to a game object related to your browser UI. This component provides the events your UI will listen on to update its display and the methods and values your UI will interact with to drive the query

Step 2

Create a UI controller that can listen on the Results Changed event of the UGC Query Manager and update your UI accordingly. That is write a new script to manage your browser UI and set it up such that it can listen on the Results Upated event of the manager
PSEDO CODE EXAMPLE
1
public void HandleResultsChanged()
2
{
3
foreach(var result in manager.activeQuery.ResultsList)
4
{
5
// Instantate a new record
6
// set its values based on the data present in result
7
}
8
}
Copied!
The above assumes you have a reference to your query manager in an attribute named manager
result will be of type UGC Read Community Item and contains all the details about that specific item.
Once defined you can reference this in the Unity Inspector

Step 3

Next you will want to connect UI controls such as a Back and Next button up so the user can iterate over the query pages.
Remember UGC Query doesn't return all the results in one batch. You will be querying "page 1" which will return a subset of items. To fetch the next set e.g. "page 2" you need to increment the Current Page value of the manager.
You should do the same for "Set Previous Search Page" so that the user can go back and forth. These methods are safe and will never step to a page that doesn't exist.

Step 4

Enabling search, you could do this in a few ways but the simplest is to trigger a search on the end edit of an InpuField, this way when the user finished typing a search string and presses enter it will start the search.
That said it can be nice to have a Search Button that on click performed the searched using the text contained in the InputField. The choice is up to you
Whatever your choice your UI should call the SearchAll method which takes a string as an input parameters. That string is the filter string used by Valve to narrow results.

Getting File Details

At various points you may need to get the details of a specific set of published files ... for example if you get the collection of subscribed files.
1
using UGC = HeathenEngineering.SteamworksIntegration.API.UserGeneratedContent.Client;
Copied!
1
var files = UGC.GetSubscribedItems();
Copied!
You will have an array of PublishedFIleId_t ... so how do you get detailed information about each of those published files such as name, size, location, etc.?
You do so via the UgcQuery tool.
1
var query = UgcQuery.Create(files);
Copied!
This will create a query that reads details for the specific files you pass in. This is referred to as a Detail Query by Valve. To get the results you simply call Execute
1
query.Execute(HandleQueryResults);
Copied!
and handle the results
1
private void HandleQueryResults(UgcQuery query)
2
{
3
foreach(var item in query.ResultList)
4
{
5
//Do Work
6
}
7
}
Copied!
To learn more about UgcQuery see its KB article.