Comment on page
UGC Query
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!
Designed to simplify the act of querying User Generated Content aka Workshop items from Steam this object can be used to create and manage queries.
The intended use is that a query will be created through one of the static Create methods to properly initialize the base query and you can then use simple calls on the object to modify the query, execute the query and step through query pages.
As with anything User Generated Content the process of querying records is done in stages. The raw API requires the following steps.
Note our UGC Query tool simplifies this for you but understanding what is happening under the hood can be helpful when debugging.
First we have to create a query handle, this is a pointer to a configuration that Valve will use when searching available UGC items. The handle is created as one of 3 types of query handles
- All Request No base filter these types of queries return all manner of UGC items. These queries use paging pulling back up to 50 at a time
- Details Request These queries take file IDs in as part of the argument and do not using paging. They only return the items you directly ask for.
- User Request These queries return items related to a given user such as a friend or your self
You will notice Heathen's UGC Query doesn't ask you what type you want. We can infer what type is needed based on the arguments you pass in on the UgcQuery.Create method.
Once you have a handle you can apply various settings to it. For example you can set the language, add tags to filter on, etc. The available settings can be accessed via the methods we describe below
Finally once we have a handle and have configured it we need to execute the query. Note that query types
All and User have pages so when you execute you may only receive a part of the total count. The pageCount field will tell you how many pages this query has once it has been executed at least once. You can set the page by simply setting the Page field or by calling SetPage. When the page is set the existing handle will be released and a new handle created.Note we release the handle for you at the end of each execution.
This means you cannot execute the same query twice, but it also means that when you forget to dispose ... Heathen has you covered.
What if you want/need to execute the same query twice?
You need to rebuild the query to do that and you can do that easily by simply calling the "Create" method again or setting the page value, even if you set it to the same value it will rebuild the same query.
You should have noticed that the UgcQuery is a "Disposable" object. This means it needs to be cleaned up when your done with it and we made that easy to do. You could simply let the .NET garbage collector handle this but its advisable to call it your self
myQuery.Dispose();This will release any open handle insure all references are free.
public class UgcQuery : IDisposable
We have created a number of Get methods you can use to quickly construct a UgcQuery to meet your needs.
public static UgcQuery Get(EUGCQuery queryType,
EUGCMatchingUGCType matchingType,
AppId_t creatorApp,
AppId_t consumerApp)
The first form of the Get method can be used with any type of query and simply gets a query ready for you to further modify.
public static UgcQuery Get(params PublishedFileId_t[] fileIds)
This form of the Get method takes one or more file IDs you would like to get more information on. This can be useful when already have a set of known file IDs such as the users subscribed IDs. You can also pass in a list or array of file IDs you would like to query.
public static UgcQuery Get(AccountID_t account,
EUserUGCList listType,
EUGCMatchingUGCType matchingType,
EUserUGCListSortOrder sortOrder,
AppId_t creatorApp,
AppId_t consumerApp)
This option lets you create a query that looks for items related to a specific user or account.
public static UgcQuery GetMyPublished()
public static UgcQuery GetMyPublished(AppData creatorApp, AppData consumerApp)
Creates a query to get all the published files related to the local user.
public static UgcQuery GetSubscribed()
The same as calling
Get(fileIds) on the set of subscribed files the local user is subscribed to. This is the easiest way to get the details about all the workshop items this user is currently using.public static UgcQuery GetPlayed()
public static UgcQuery GetPlayed(AppData creatorApp, AppData consumerApp)
Gets the set of workshop items the local player has played
public UGCQueryHandle_t handle
The active query handle if any. This can be used to modify the query acter creating it. In most cases you wont need to use this directly.
public uint matchedRecordCount
The number of matched records. This will be 0 untill the query is executed and should not be updated manually.
public uint pageCount
The number of pages found for this query. This will be 0 until the query is exeucted and should not be updated manually.
public uint Page { get; set; }
public List<UGCCommunityItem> ResultsList
This will be populated with the results when the query is executed ... assuming there are results to populate.
public bool AddExcludedTag(string tagName);
Adds a excluded tag to a pending UGC Query. This will only return UGC without the specified tag.
public bool AddRequiredKeyValueTag(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.
public bool AddRequiredTag(string tagName)
Adds a required tag to a pending UGC Query. This will only return UGC with the specified tag.
public bool SetAllowCachedResponse(uint maxAgeSeconds)
Set allow cached response from UGC Query
public bool SetCloudFileNameFilter(string fileName)
Set the cloud file name filter value
public bool SetLanguage(string language);
Sets the query item language
public bool SetMatchAnyTag(bool anyTag)
Sets the query match any tag
public bool SetRankedByTrendDays(uint days);
Sets the query to rank by trend over the indicated days
public bool SetReturnAdditionalPreviews(bool enable);
Should the query return additional previews or just the main
public bool SetReturnChildren(bool enable);
Should the query return child items or just the main
public bool SetReturnKeyValueTags(bool enable);
Should the query return key value tags
public bool SetReturnLongDescription(bool enable);
Should the query return the long description of the item
public bool SetReturnMetadata(bool enable);
Should the query return metadata
public bool SetReturnOnlyIDs(bool enable);
Should the query only return item IDs
public bool SetReturnPlaytimeStats(uint days);
Over what set of days should paly time stats be returned
public bool SetReturnTotalOnly(bool enable);
Should the query only return the matching count and not item data at all
public bool SetSearchText(string text);
Sets the search text to be used by the query
public bool SetNextPage();
Advances the active page forward by 1 if available
public bool SetPreviousPage();
Steps back to the previous page if available
public bool SetPage(uint page);
Sets the query to the indicated page
public bool Execute(UnityAction<UgcQuery> callback);
Executes the given query and registers a callback to catch its results
public void ReleaseHandle();
Releases the query handle, this should be called when done with a query. This is automatically called when the object is disposed.
public void Dispose();
Deconstructs the query and frees its handles
Last modified 1mo ago