ISteamUGC

Function Reference

UGC.createItem(consumerAppId, fileType, callback)
Parameters:
  • consumerAppId (number) – The App ID that will be using this item.
  • fileType (string) – The type of UGC to create. Must be one of ‘Community’, ‘Microtransaction’, ‘Collection’, ‘Art’, ‘Video’, ‘Screenshot’, ‘WebGuide’, ‘IntegratedGuide’, ‘Merch’, ‘ControllerBinding’, ‘SteamVideo’ or ‘GameManagedItem’ (see EWorkshopFileType).
  • callback (function) – Called asynchronously when this function returns. See below.
Returns:

nothing

SteamWorks:

CreateItem

Creates a new workshop item with no content attached yet.

callback(data, err) receives two arguments:

  • data (table) – Similar to CreateItemResult_t, or nil if err is true.

    • data.result (number) – The result of the operation. See EResult.
    • data.publishedFileId (uint64) – The new items unique ID.
    • data.userNeedsToAcceptWorkshopLegalAgreement (boolean) – Does the user need to accept the Steam Workshop legal agreement (true) or not (false)? See the Workshop Legal Agreement for more information.
  • err (boolean): true if there was any IO error with the request.

Example:

Steam.UGC.createItem(Steam.utils.getAppID(), "Community", function(data, err)
    if err or data.result ~= 1 then
        print('Failure when creating item')
    else
        populateItem(data.publishedFileId)
    end
end)
UGC.startItemUpdate(consumerAppId, publishedFileId)
Parameters:
  • consumerAppId (number) – The App ID that will be using this item.
  • publishedFileId (uint64) – The item to update.
Returns:

(uint64) A handle that you can use with future calls to modify the item before finally sending the update.

SteamWorks:

StartItemUpdate

Starts the item update process.

This gets you a handle that you can use to modify the item before finally sending off the update to the server with UGC.submitItemUpdate().

Example:

local function populateItem(id)
    local handle = Steam.UGC.startItemUpdate(Steam.utils.getAppID(), id)
    Steam.UGC.setItemContent(handle, rootFolder)
    Steam.UGC.setItemTitle(handle, "My Item")
    Steam.UGC.setItemDescription(handle, "A Workshop item")
    Steam.UGC.setItemPreview(handle, rootFolder .. '/preview.png')
    Steam.UGC.submitItemUpdate(handle, "First Revision", function(data, err)
        if err or data.result ~= 1 then
            print('Update failed')
        else
            print('Update successfull')
        end
    end)
end
UGC.setItemContent(updateHandle, contentFolder)
Parameters:
  • updateHandle (uint64) – The workshop item update handle to customize.
  • contentFolder (string) – The absolute path to a local folder containing the content for the item.
Returns:

(boolean) true upon success. false if the UGC update handle is invalid.

SteamWorks:

SetItemContent

Sets the folder that will be stored as the content for an item.

For efficient upload and download, files should not be merged or compressed into single files (e.g. zip files).

Note

This must be set before you submit the UGC update handle using UGC.submitItemUpdate().

Example:: See UGC.startItemUpdate()’s example.

UGC.setItemDescription(updateHandle, description)
Parameters:
  • updateHandle (uint64) – The workshop item update handle to customize.
  • description (string) – The new description of the item.
Returns:

(boolean) true upon success. false if the UGC update handle is invalid.

SteamWorks:

SetItemDescription

Sets a new description for an item.

The description must be limited to the length defined by k_cchPublishedDocumentDescriptionMax.

You can set what language this is for by using UGC.setItemUpdateLanguage() (missing), if no language is set then “english” is assumed.

Note

This must be set before you submit the UGC update handle using UGC.submitItemUpdate().

Example:: See UGC.startItemUpdate()’s example.

UGC.setItemPreview(updateHandle, previewFile)
Parameters:
  • updateHandle (uint64) – The workshop item update handle to customize.
  • previewFile (string) – The absolute path to a local preview image file for the item.
Returns:

true upon success. false if the UGC update handle is invalid.

SteamWorks:

SetItemPreview

Sets the primary preview image for the item.

The format should be one that both the web and the application (if necessary) can render. Suggested formats include JPG, PNG and GIF.

Note

This must be set before you submit the UGC update handle using UGC.submitItemUpdate().

Example:: See UGC.startItemUpdate()’s example.

UGC.setItemTitle(updateHandle, title)
Parameters:
  • updateHandle (uint64) – The workshop item update handle to customize.
  • title (string) – The new title of the item.
Returns:

(boolean) true upon success. false if the UGC update handle is invalid.

SteamWorks:

SetItemTitle

Sets a new title for an item.

The title must be limited to the size defined by k_cchPublishedDocumentTitleMax.

You can set what language this is for by using UGC.setItemUpdateLanguage(), if no language is set then “english” is assumed.

Note

This must be set before you submit the UGC update handle using UGC.submitItemUpdate().

Example:: See UGC.startItemUpdate()’s example.

UGC.submitItemUpdate(updateHandle, changeNote, callback)
Parameters:
  • updateHandle (uint64) – The update handle to submit.
  • changeNote (string?) – A brief description of the changes made (Optional, set to nil for no change note).
  • callback (function) – Called asynchronously when this function returns. See below.
Returns:

nothing

SteamWorks:

SubmitItemUpdateResult

Uploads the changes made to an item to the Steam Workshop.

You can track the progress of an item update with UGC.getItemUpdateProgress().

callback(data, err) receives two arguments:

  • data (table) – Similar to SubmitItemUpdateResult_t, or nil if err is true.

    • data.result (number) – The result of the operation. See EResult.
    • data.userNeedsToAcceptWorkshopLegalAgreement (boolean) – Does the user need to accept the Steam Workshop legal agreement (true) or not (false)? See the Workshop Legal Agreement for more information.
  • err (boolean): true if there was any IO error with the request.

Example:: See UGC.startItemUpdate()’s example.

UGC.getNumSubscribedItems()
Returns:(number) Total number of subscribed items. 0 if called from a game server.
SteamWorks:GetNumSubscribedItems

Gets the total number of items the current user is subscribed to for the game or application.

Example:

print('You are subscribed to ' .. Steam.UGC.getNumSubscribedItems() .. ' items')
UGC.getSubscribedItems()
Returns:(table) An array of PublishedFileId (more precisely, uint64) for all your subscribed items. Empty if called from a game server.
SteamWorks:GetSubscribedItems

Gets a list of all of the items the current user is subscribed to for the current game.

Warning

This function is slightly different from the SteamWorks API. You don’t need to send the array, it is returned by the function.

Example:

for _, id in ipairs(Steam.UGC.getSubscribedItems()) do
    local flag = Steam.UGC.getItemState(id)
    if flag.installed then
        print('Subscribed item is installed!')
        local success, sizeOnDisk, folder = Steam.UGC.getItemInstallInfo(id)
        print('Install location: ' .. folder)
        print('Install size: ' .. sizeOnDisk)
    elseif flag.downloading then
        print('Subscribed item is downloading!')
    else
        print('Subscribed item is doing something')
    end
end
UGC.getItemState(publishedFileId)
Parameters:publishedFileId (uint64) – The workshop item to get the state for.
Returns:(table) A table with flags for the item state, or nil if the item is not tracked on client. All flags are boolean values.
  • subscribed – The current user is subscribed to this item. Not just cached.
  • legacyItem – The item was created with the old workshop functions in ISteamRemoteStorage.
  • installed – Item is installed and usable (but maybe out of date).
  • needsUpdate – The items needs an update. Either because it’s not installed yet or creator updated the content.
  • downloading – The item update is currently downloading.
  • downloadPendingUGC.downloadItem() (missing) was called for this item, the content isn’t available until the callback is fired.
SteamWorks:GetItemState

Gets the current state of a workshop item on this client.

Example:: See UGC.getSubscribedItems()’s example.

UGC.getItemInstallInfo(id)
Returns:(boolean) true if the operation is successfull. false in the following cases:
  • cchFolderSize is 0.
  • The workshop item has no content.
  • The workshop item is not installed.

If this value is false, nothing else is returned. Otherwise:

Returns:(number) Returns the size of the workshop item in bytes.
Returns:(string) Returns the absolute path to the folder containing the content.
Returns:(number) Returns the time when the workshop item was last updated.
SteamWorks:GetItemInstallInfo

Gets info about currently installed content on the disc for workshop items that have installed set.

Calling this sets the “used” flag on the workshop item for the current player and adds it to their usedOrPlayed list.

If legacyItem is set then folder contains the path to the legacy file itself, not a folder.

Example:: See UGC.getSubscribedItems()’s example.

UGC.getItemUpdateProgress(handle)
Parameters:handle (uint64) – The update handle to get the progress for.
Returns:(string) The current status. One of ‘Invalid’, ‘PreparingConfig’, ‘PreparingContent’, ‘UploadingContent’, ‘UploadingPreviewFile’, ‘CommittingChanges’. See EItemUpdateStatus.
Returns:(number) The current number of bytes uploaded.
Returns:(number) The total number of bytes that will be uploaded.
SteamWorks:GetItemUpdateProgress

Gets the progress of an item update.

Example:

local rev = {
    PreparingConfig = 0,
    PreparingContent = 1,
    UploadingContent = 2,
    UploadingPreviewFile = 3,
    CommittingChanges = 4,
    Invalid = 5, -- also Invalid when the job is finished
}
local function get_progress(handle)
    local st, uploaded, total = Steam.UGC.getItemUpdateProgress(handle)
    local p = rev[st] / 5
    -- total may be 0 depending on the status
    if total ~= 0 then
        p = p + 0.2 * (uploaded / total)
    end
    return p
end
UGC.startPlaytimeTracking(vec, callback)
Parameters:
  • vec (table) – The array of workshop items (PublishedFileId, more precisely uint64) you want to start tracking. (Maximum of 100 items.)
  • callback (function) – Called asynchronously when this function returns. It is only called if you send between 1 and 100 items. See below.
Returns:

nothing

SteamWorks:

StartPlaytimeTracking

Start tracking playtime on a set of workshop items.

When your app shuts down, playtime tracking will automatically stop. callback(data, err) receives two arguments:

  • data (table) – Similar to StartPlaytimeTrackingResult_t, or nil if err is true.

    • data.result (number) – The result of the operation. See EResult.
  • err (boolean): true if there was any IO error with the request.

Example:

-- Tracks all subscribed items (you probably shouldn't do this)
Steam.UGC.startPlaytimeTracking(Steam.UGC.getSubscribedItems(), function(data, err)
    if not err and data.result == 1 then
        print('Tracking succeded')
    end
end)
UGC.stopPlaytimeTracking(vec, callback)
Parameters:
  • vec (table) – The array of workshop items (PublishedFileId, more precisely uint64) you want to stop tracking. (Maximum of 100 items.)
  • callback (function) – Called asynchronously when this function returns. It is only called if you send between 1 and 100 items. See below.
Returns:

nothing

SteamWorks:

StopPlaytimeTracking

Stop tracking playtime on a set of workshop items.

When your app shuts down, playtime tracking will automatically stop.

callback(data, err) receives two arguments:

  • data (table) – Similar to StopPlaytimeTrackingResult_t, or nil if err is true.

    • data.result (number) – The result of the operation. See EResult.
  • err (boolean): true if there was any IO error with the request.

Example:

local function stopTracking(...)
    Steam.UGC.stopPlaytimeTracking({...}, function(data, err)
        if not err and data.result == 1 then
            print('Tracking successfully stopped')
        end
    end)
end
UGC.stopPlaytimeTrackingForAllItems(callback)
Parameters:callback (function) – Called asynchronously when this function returns. It must be of the same type as the callback in UGC.stopPlaytimeTracking().
Returns:nothing
SteamWorks:StopPlaytimeTracking

Stop tracking playtime of all workshop items.

When your app shuts down, playtime tracking will automatically stop.

Example:

Steam.UGC.stopPlaytimeTrackingForAllItems(function(data, err)
    if not err and data.result == 1 then
        print('Tracking successfully stopped for all items')
    end
end)