UserGeneratedContent.Client
Like what your seeing?
Support us as a GitHub Sponsor and get instant access to all our assets, exclusive tools and assets, escalated support and issue tracking and our gratitude. These articles are made possible by our GitHub Sponsors ... become a sponsor today!
Introduction
using UGCClient= HeathenEngineering.SteamworksIntegration.API.UserGeneratedContent.Client;public static class UserGeneratedContent.ClientEvents
EventItemDownloaded
Occurs when a UGC item is downloaded
public static WorkshopDownloadedItemResultEvent EventItemDownloaded;The event handler would look similar to
void HandleEvent(DownloadItemResult_t arg0)
{
//Do Work
}EventWorkshopItemInstalled
Called when a workshop item has been installed or updated
public static WorkshopItemInstalledEvent EventWorkshopItemInstalled;The event handler would look similar to
void HandleEvent(ItemInstalled_t arg0)
{
//Do Work
}Methods
AddAppDependency
public static void AddAppDependency(PublishedFileId_t fileId,
AppId_t appId,
Action<AddAppDependencyResult_t, bool> callback)The callback for this method would look like the following.
void Callback(AddAppDependencyResult_t responce, bool ioError)
{
// Do Work
}Adds a dependency between the given item and the appid. This list of dependencies can be retrieved by calling GetAppDependencies. This is a soft-dependency that is displayed on the web. It is up to the application to determine whether the item can actually be used or not.
AddDependency
public static void AddDependency(PublishedFileId_t parentFileId,
PublishedFileId_t childFileId,
Action<AddUGCDependencyResult_t, bool> callback)void Callback(AddUGCDependencyResult_t responce, bool ioError)
{
// Do Work
}Adds a workshop item as a dependency to the specified item. If the nParentPublishedFileID item is of type k_EWorkshopFileTypeCollection, than the nChildPublishedFileID is simply added to that collection. Otherwise, the dependency is a soft one that is displayed on the web and can be retrieved via the ISteamUGC API using a combination of the m_unNumChildren member variable of the SteamUGCDetails_t struct and GetQueryUGCChildren.
AddExcludedTag
public static bool AddExcludedTag(UGCQueryHandle_t handle, string tagName)Adds a excluded tag to a pending UGC Query. This will only return UGC without the specified tag.
AddItemKeyValueTag
public static bool AddItemKeyValueTag(UGCUpdateHandle_t handle,
string key, string value)Adds a key-value tag pair to an item. Keys can map to multiple different values (1-to-many relationship). Key names are restricted to alpha-numeric characters and the '_' character. Both keys and values cannot exceed 255 characters in length. Key-value tags are searchable by exact match only.
AddItemPreviewFile
public static bool AddItemPreviewFile(UGCUpdateHandle_t handle,
string previewFile, EItemPreviewType type)Adds an additional preview file for the item. Then the format of the image should be one that both the web and the application(if necessary) can render, and must be under 1MB.Suggested formats include JPG, PNG and GIF.
AddItemPreviewVideo
public static bool AddItemPreviewVideo(UGCUpdateHandle_t handle, string videoId)Adds an additional video preview from YouTube for the item.
AddItemToFavorites
public static void AddItemToFavorites(AppId_t appId,
PublishedFileId_t fileId,
Action<UserFavoriteItemsListChanged_t, bool> callback)Adds workshop item to the users favorite list. The callback to this method would look like the following
void Callback(UserFavoriteItemsListChanged_t responce, bool ioError)
{
// Do Work
}AddRequiredKeyValueTag
public static bool AddRequiredKeyValueTag(UGCQueryHandle_t handle,
string key, string value)Adds a required key-value tag to a pending UGC Query. This will only return workshop items that have a key = pKey and a value = pValue.
AddRequiredTag
public static bool AddRequiredTag(UGCQueryHandle_t handle, string tagName)Adds a required tag to a pending UGC Query. This will only return UGC with the specified tag.
CreateItem
public static bool CreateItem(WorkshopItemData item,
WorkshopItemPreviewFile[] additionalPreviews,
string[] additionalYouTubeIds,
WorkshopItemKeyValueTag[] additionalKeyValueTags,
Action<WorkshopItemDataCreateStatus> callback = null)The first overload handles the creation and update of new items in a single line call.
The first parameter defines the core fields of the item to be created, note the WorkshopItemData.Create method simply calls this overload.
The remaining parameters deal with additional preview images and videos as well as the key value tag system
The callback for this overload would look similar to following.
void Callback(WorkshopItemDataCreateStatus status)
{
//Do Work
}The second overload is only creates an empty UGC File. You would then manually start the update process and set each of its fields. This approach is more akin to using the Raw Steam API.
public static void CreateItem(AppId_t appId, EWorkshopFileType type,
Action<CreateItemResult_t, bool> callback)The callback for this overload would look similar to the following.
void Callback(CreateItemResult_t responce, bool ioError)
{
// Do Work
}This works exsactly the same as the native Steam API callback as documented here and uses those native Steam API structures.
CreateQueryAllRequest
public static UGCQueryHandle_t CreateQueryAllRequest(EUGCQuery queryType,
EUGCMatchingUGCType matchingFileType,
AppId_t creatorAppId,
AppId_t consumerAppId,
uint page)Query for all matching UGC. You can use this to list all of the available UGC for your app. You must release the handle returned by this function by calling WorkshopReleaseQueryRequest when you are done with it!
CreateQueryDetailsRequest
All of the overloads do the same thing they simply reduce the need for in line conversion when using different types of collecitons.
public static UGCQueryHandle_t CreateQueryDetailsRequest(
PublishedFileId_t[] fileIds)public static UGCQueryHandle_t CreateQueryDetailsRequest(
List<PublishedFileId_t> fileIds)public static UGCQueryHandle_t CreateQueryDetailsRequest(
IEnumerable<PublishedFileId_t> fileIds)Query for the details of specific workshop items. You must release the handle returned by this function by calling WorkshopReleaseQueryRequest when you are done with it!
CreateQueryUserRequest
public static UGCQueryHandle_t CreateQueryUserRequest(
AccountID_t accountId,
EUserUGCList listType,
EUGCMatchingUGCType matchingType,
EUserUGCListSortOrder sortOrder,
AppId_t creatorAppId,
AppId_t consumerAppId,
uint page)Query UGC associated with a user. You can use this to list the UGC the user is subscribed to amongst other things. You must release the handle returned by this function by calling WorkshopReleaseQueryRequest when you are done with it!
ReleaseQueryRequest
public static bool ReleaseQueryRequest(UGCQueryHandle_t handle)Frees a UGC query
DeleteItem
public static void DeleteItem(PublishedFileId_t fileId,
Action<DeleteItemResult_t, bool> callback)Requests delete of a UGC item
void Callback(DeleteItemResult_t responce, bool ioFailure)
{
//Do Work
}DownloadItem
public static bool DownloadItem(PublishedFileId_t fileId, bool setHighPriority)Request download of a UGC item
GetAppDependencies
public static void GetAppDependencies(PublishedFileId_t fileId,
Action<GetAppDependenciesResult_t, bool> callback)Request the app dependencies of a UGC item
GetItemDownloadInfo
public static bool GetItemDownloadInfo(PublishedFileId_t fileId,
out float completion)Request the download informaiton of a UGC item
GetItemInstallInfo
public static bool GetItemInstallInfo(PublishedFileId_t fileId,
out ulong sizeOnDisk,
out string folderPath,
out DateTime timeStamp)Request the installation informaiton of a UGC item
GetItemInstallInfo
public static bool GetItemInstallInfo(PublishedFileId_t fileId,
out ulong sizeOnDisk,
out string folderPath,
uint folderSize,
out DateTime timeStamp)Request the installation informaiton of a UGC item
GetItemState
public static EItemState GetItemState(PublishedFileId_t fileId)Gets the current state of a workshop item on this client.
ItemStateHasFlag
public static bool ItemStateHasFlag(EItemState value, EItemState checkflag)Checks if the 'checkFlag' value is in the 'value'
ItemStateHasAllFlags
public static bool ItemStateHasAllFlags(EItemState value,
params EItemState[] checkflags)Cheks if any of the 'checkflags' values are in the 'value'
GetItemUpdateProgress
public static EItemUpdateStatus GetItemUpdateProgress(UGCUpdateHandle_t handle,
out float completion)Gets the progress of an item update.
GetNumSubscribedItems
public static uint GetNumSubscribedItems()Returns the number of subscribed UGC items
GetQueryAdditionalPreview
public static bool GetQueryAdditionalPreview(UGCQueryHandle_t handle,
uint index,
uint previewIndex,
out string urlOrVideoId,
uint urlOrVideoSize,
string fileName,
uint fileNameSize,
out EItemPreviewType type)Request an additional preview for a UGC item
GetQueryChildren
public static bool GetQueryChildren(UGCQueryHandle_t handle,
uint index,
PublishedFileId_t[] fileIds,
uint maxEntries)Request the child items of a given UGC item
GetQueryKeyValueTag
public static bool GetQueryKeyValueTag(UGCQueryHandle_t handle,
uint index,
uint keyValueTagIndex,
out string key,
string value)Retrieve the details of a key-value tag associated with an individual workshop item after receiving a querying UGC call result.
GetQueryMetadata
public static bool GetQueryMetadata(UGCQueryHandle_t handle,
uint index,
out string metadata,
uint size)Request the metadata of a UGC item
GetQueryNumAdditionalPreviews
public static uint GetQueryNumAdditionalPreviews(UGCQueryHandle_t handle,
uint index)Request the number of previews of a UGC item
GetQueryNumKValueTags
public static uint GetQueryNumKeyValueTags(UGCQueryHandle_t handle, uint index)Request the number of key value tags for a UGC item
GetQuyPreviewURL
public static bool GetQueryPreviewURL(UGCQueryHandle_t handle,
uint index,
out string URL,
uint urlSize)Get the preview URL of a UGC item
GetQueryResults
public static bool GetQueryResult(UGCQueryHandle_t handle,
uint index,
out SteamUGCDetails_t details)Fetch the results of a UGC query
GetQueryStatistic
public static bool GetQueryStatistic(UGCQueryHandle_t handle,
uint index,
EItemStatistic statType,
out ulong statValue)Fetch the statistics of a UGC query
GetSubscribedItems
public static uint GetSubscribedItems(PublishedFileId_t[] fileIDs,
uint maxEntries)Get the file IDs of all subscribed UGC items up to the array size. This is a wrapper around the raw API entry and maintained for backward compatibility.
or
public static PublishedFileId_t[] GetSubscribedItems()Returns the list of items the user is subscribed to as a simple array.
or
public static void GetSubscribedItems(Action<List<UGCCommunityItem>> callback)This will query for the details of the items the user is subscribed to and invoke a callback when those details are returned.
GetUserItemVote
public static void GetUserItemVote(PublishedFileId_t fileId,
Action<GetUserItemVoteResult_t, bool> callback)Get the item vote value of a UGC item. The callback for this would look like the following
void Callback(GetUserItemVoteResult_t responce, bool ioFailure)
{
// Do Work
}GetWorkshopEULAStatus
public static void GetWorkshopEULAStatus(
Action<WorkshopEULAStatus_t, bool> callback)Asynchronously retrieves data about whether the user accepted the Workshop EULA for the current app. The callback for this method would look like the following.
void Callback(WorkshoEULAStatus_t responce, bool ioFailure)
{
// Do Work
}ShowWorkshopEULA
public static bool ShowWorkshopEULA()Show the app's latest Workshop EULA to the user in an overlay window, where they can accept it or not
RemoveAppDependency
public static void RemoveAppDependency(PublishedFileId_t fileId,
AppId_t appId,
Action<RemoveAppDependencyResult_t, bool> callback)Request the removal of app dependency from a UGC item
RemoveDependency
public static void RemoveDependency(PublishedFileId_t parentFileId,
PublishedFileId_t childFileId,
Action<RemoveUGCDependencyResult_t, bool> callback)Request the removal of a dependency from a UGC item
RemoveItemFromFavorites
public static void RemoveItemFromFavorites(AppId_t appId,
PublishedFileId_t fileId,
Action<UserFavoriteItemsListChanged_t, bool> callback)Request the item be removed from the user's favourites list if present
RemoveItemKeyValueTags
public static bool RemoveItemKeyValueTags(UGCUpdateHandle_t handle, string key)Remove UGC Item key value tags
RemoveItemPreview
public static bool RemoveItemPreview(UGCUpdateHandle_t handle, uint index)Remove UGC Item Preview
RequestDetails
public static void RequestDetails(PublishedFileId_t fileId,
uint maxAgeSeconds,
Action<SteamUGCRequestUGCDetailsResult_t, bool> callback)Request details of a given UGC item
SendQueryUGCRequest
public static void SendQueryUGCRequest(UGCQueryHandle_t handle,
Action<SteamUGCQueryCompleted_t, bool> callback)Send a UGC query for processing
SetAllowCashedResponse
public static bool SetAllowCachedResponse(UGCQueryHandle_t handle,
uint maxAgeSeconds)Set the allow cashed response on Steam
SetCloudFileNameFilter
public static bool SetCloudFileNameFilter(UGCQueryHandle_t handle,
string fileName)Set the file name filter value for use with queries
SetItemContent
Sets the folder path that Valve will upload from when submitting an item update
SetItemDescription
Sets the item description of the item when submitting an item update
SetItemMetadata
Sets the item metadata of the item when submitting an item update
SetItemPreview
SetItemTags
SetItemTitle
SetItemUpdateLanguage
SetItemVisibility
SetLanguage
SetMatchAnyTag
SetRankedByTrendDays
SetReturnAdditionalPreviews
SetReturnChildren
SetReturnKeyalueTags
SetReturnLongDescription
SetReturnMetadata
SetReturnOnlyIDs
SetReturnPlaytimeStats
public static bool SetReturnPlaytimeStats(UGCQueryHandle_t handle, uint days)Set a query to return the playtime stats for related items
SetReturnTotalOnly
public static bool SetReturnTotalOnly(UGCQueryHandle_t handle, bool totalOnly)Set a query to only return the total number of files that match the arguments
SetSearchText
public static bool SetSearchText(UGCQueryHandle_t handle, string text)Sets the search text used when executing a UGC query
SetUserItemVote
public static void SetUserItemVote(PublishedFileId_t fileID,
bool voteUp,
Action<SetUserItemVoteResult_t, bool> callback)Sets the vote value for a given item from this user.
StartItemUpdate
public static UGCUpdateHandle_t StartItemUpdate(AppId_t appId,
PublishedFileId_t fileID)Request the start of an item update. This must be called before you set item preview, description, etc.
StartPlaytimeTracking
public static void StartPlaytimeTracking(PublishedFileId_t[] fileIds,
Action<StartPlaytimeTrackingResult_t, bool> callback)Start tracking playtime for the indicated items.
StopPlaytimeTracking
public static void StopPlaytimeTracking(PublishedFileId_t[] fileIds,
Action<StopPlaytimeTrackingResult_t, bool> callback)Stop tracking playtime for the indicated items.
StopPlaytimeTrackingForAllItems
public static void StopPlaytimeTrackingForAllItems(
Action<StopPlaytimeTrackingResult_t, bool> callback)Stop tracking playtime for all relevant items
SubmitItemUpdate
public static void SubmitItemUpdate(UGCUpdateHandle_t handle,
string changeNote,
Action<SubmitItemUpdateResult_t, bool> callback)Submit an update request committing any changes made since the StartItemUpdate request.
SubscribeItem
public static void SubscribeItem(PublishedFileId_t fileId,
Action<RemoteStorageSubscribePublishedFileResult_t, bool> callback)Subscribe to the indicated item
SuspendDownloads
public static void SuspendDownloads(bool suspend)Suspend downloads
UnsubscribeItem
public static void UnsubscribeItem(PublishedFileId_t fileId,
Action<RemoteStorageUnsubscribePublishedFileResult_t, bool> callback)Unsubscribe to the indicated item
UpdateItemPreviewFile
public static bool UpdateItemPreviewFile(UGCUpdateHandle_t handle,
uint index,
string file)Update item preview image file
UpdateItemPreviewVideo
public static bool UpdateItemPreviewVideo(UGCUpdateHandle_t handle,
uint index,
string videoId)Update item preview video
How To
Create and Update Items
Creating a new item can be done in one of two ways.
One liner
UGC.CreateItem(itemdata, callback);When using the 1 liner approach you will first create a Workshop Item Data object. This object defines the item you wish to create e.g. its name, description, content folder, etc.
The callback for this method is a delegate that takes 1 parameter of type Workshop Item Data Create Status.
Example:
Assuming a method such as
public void Foo(WorkshopItemDataCreateStats status)
{
if(!status.hasError)
//Do Work
else
//Something bad happened
}Then you can call the method such as
UGC.CreateItem(itemdata, Foo);To learn more about callbacks please read the related article.
The status returned to the callback will indicate the status of the operation. Note that the operation occurs in two stages. First a blank item is created and then once that has been found successful that blank item will be updated with the content and settings indicated thus it is possible for a blank item to be created but for the update to fail. Please see the results in the status object for more details.
Step by step
UGC.CreateItem(appId, callback);This callback will contain a UGCUpdateHandle_t which can be used by other methods to update key features using the following methods
You can also use these tools to modify and existing file assuming you are its author
UGC.StartItemUpdate(appId, fileId);AddItemKeyValueTag
AddItemPreviewFile
AddItemPreviewVideo
SetItemContent
SetItemDescription
SetItemMetadata
SetItemPreview
SetItemTags
SetItemTitle
SetItemUpdateLanguage
SetItemVisibility
UpdateItemPreviewVideo
UpdateItemPreviewFIle
UpdateItemPreviewVideo
RemoveItemKeyValueTags
RemoveItemPreview
For example the following code would update the title and description
UGC.SetItemTitle(updateHandle, "title");
UGC.SetItemDescription(updatehandle, "description");When complete you should submit the update
UGC.SubmitItemUpdate(handle, changenote, callback);Browse Items
The easiest way to handle a UGC / Workshop browser in game is to use the UGC Query Manager. The manager uses the same features present in the interface so it can be done manually.
The remainder of this section talks about manually querying items.
The process is similar in that you would "create" or "start" a query which will give you a UGCQueryHandle_t which can then be modified to fine tune your query before submitting it to get the matching records.
To crete the UGCQueryHandle_t
//Query all UGC for a particular App ID
var handle = UGC.CreateQueryAllRequest(type,
fileType,
creatAppId,
consumeAppId,
page);
// or
//Query for specific files by file ID
var handle = UGC.CreateQueryDetailRequest(files);
//or
//Query for files related to a specific user
var handle = UGC.CreateQueryUserRequest(account,
listType,
matchType,
sortOrder,
createAppId,
consumeAppId,
page);Once you have created your handle you can modify the way it searches for matching items by calling the following methods.
AddExcludeTag
AddRequiredKeyValueTag
AddRequiredTag
SetAllowCashedResponse
SetCloudFileNameFilter
SetLanguage
SetMatchAnyTag
SetRankedByTrendDays
SetReturnAdditionalPreviews
SetReturnChildren
SetReturnKeyValueTags
SetReturnLongDescription
SetReturnMetadata
SetReturnOnlyIDs
SetReturnPlaytimeStats
SetReturnTotalOnly
SetSearchText
Once you have your query set up you can submit it to fetch the related items. Note the UGC Query system is a page query system. It will never return more than 50 items (determined by Valve) and so you will need to increment the page in your query handle to fetch each successive set of records.
You can see how we implemented paging in the UGC Query Manager if you wished to do so your self or simply to better understand the system.
//When ready send the query so Valve can process it
UGC.SendQueryUGCRequest(handle, callback);When the callback is invoked its parameter will indicate the result state and query handle, assuming the state is eResultOk you can fetch the found items via, the following assumes param is the SteamUGCQueryComplete_t object returned by the SendQueryUGCRequest's callback
//If nothing went wrong
if(param.m_eResult == EResult.k_EResultOK)
{
//Get the total records found
var totalResults = param.m_unTotalMatchingResutls;
//Get the number of pages involved
var pageCount = (uint)MathF.Clamp((int)matchedRecordCount / 50, 1, int.MaxValue);
if(pageCount * 50 < matchedRecordCount)
pageCount++;
//Get the number of results in this run/page
var returned = param.m_unNumResultsReturned;
for(int i=0; i < returned; i++)
{
UGC.GetQueryResult(param.m_handle,
(uint)i,
out SteamUGCDetails_t detail);
//detail now contains all of the data for this item, do with it what you will
}
//We must release the handle when done reading it
UGC.ReleaseQueryRequest(param.m_handle);
}Getting the next page of data is done the same way, you will need to track what page your on and howmany there are and create a new query updating the page.
Our UGC Query Manager does this fore you. You can simply incrament the page by calling SetPage and we will release any existing handle and fetch a new handle for the next page. You will need to re apply any modifications to the query you may have done before executing it again.
Get Subscribed Items
To get the list of subscirbed items e.g. items the user has indicated should be installed
var results = UGC.GetSubscribedItems();Last updated