Engine

ContentProvider

Show Deprecated
not creatable
service
not replicated

Service that is used to load content, or assets, into a game.

The service's main use is to preload assets into a game. When a new asset such as a Decal or Sound is used in a game, Roblox will load the content associated with it from Roblox servers. In some cases, this can be undesirable for developers as it can lead to a delay before the content loads into the game.

With ContentProvider, developers can preload assets using the ContentProvider:PreloadAsync() function. Another useful property is ContentProvider.RequestQueueSize, which can be used to measure what proportion of assets in the request queue have been downloaded.

Code Samples

ContentProvider

local ContentProvider = game:GetService("ContentProvider")
local LOGO_ID = "rbxassetid://658743164"
local PAGE_TURN_ID = "rbxassetid://12222076"
local decal = Instance.new("Decal")
decal.Texture = LOGO_ID
local sound = Instance.new("Sound")
sound.SoundId = PAGE_TURN_ID
local assets = { decal, sound }
ContentProvider:PreloadAsync(assets)
print("All assets loaded.")

Summary

Properties

Methods

Properties

BaseUrl

read only
not replicated
read parallel

Used by the ContentProvider to download assets from the Roblox website.

This URL points to a Roblox hosted website from which assets are downloaded and is pulled from the AppSettings.xml file, located in the version-hash folder.

It is possible to overwrite this property using the ContentProvider:SetBaseUrl() function in the command bar; however, this is not recommended and may cause asset loading issues.

RequestQueueSize

read only
not replicated
read parallel

Gives the number of items in the ContentProvider request queue that need to be downloaded.

Items are added to the client's request queue when an asset is used for the first time or ContentProvider:PreloadAsync() is called.

Developers are advised not to use RequestQueueSize to create loading bars. This is because the queue size can both increase and decrease over time as new assets are added and downloaded. Developers looking to display loading progress should load assets one at a time (see example below).

Code Samples

ContentProvider Loading Bar

local ContentProvider = game:GetService("ContentProvider")
local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local playerGui = localPlayer:WaitForChild("PlayerGui")
local screenGui = Instance.new("ScreenGui")
screenGui.Parent = playerGui
-- create a basic loading bar
local frame = Instance.new("Frame")
frame.Size = UDim2.new(0.5, 0, 0.1, 0)
frame.Position = UDim2.new(0.5, 0, 0.5, 0)
frame.AnchorPoint = Vector2.new(0.5, 0.5)
frame.Parent = screenGui
local bar = Instance.new("Frame")
bar.Size = UDim2.new(0, 0, 1, 0)
bar.Position = UDim2.new(0, 0, 0, 0)
bar.BackgroundColor3 = Color3.new(0, 0, 1)
bar.Parent = frame
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
local sound2 = Instance.new("Sound")
sound2.SoundId = "rbxassetid://9120385974"
local assets = {
sound,
sound2,
}
task.wait(3)
for i = 1, #assets do
local asset = assets[i]
ContentProvider:PreloadAsync({ asset }) -- 1 at a time, yields
local progress = i / #assets
bar.Size = UDim2.new(progress, 0, 1, 0)
end
print("loading done")

Methods

GetAssetFetchStatus

Gets the current Enum.AssetFetchStatus of the contentId provided. Use GetAssetFetchStatusChangedSignal() to listen for changes to this value.

Parameters

contentId: Content

The ID of the content to fetch the status for.


Returns

Code Samples

Monitoring AssetFetchStatus

local ContentProvider = game:GetService("ContentProvider")
-- An example asset to load
local ASSET_ID = "rbxassetid://9120386436"
local exampleAsset = Instance.new("Sound")
exampleAsset.SoundId = ASSET_ID
-- Output the current AssetFetchStatus of the asset
local initialAssetFetchStatus = ContentProvider:GetAssetFetchStatus(ASSET_ID)
print("Initial AssetFetchStatus:", initialAssetFetchStatus)
-- Listen for updates
local assetFetchStatusChangedSignal = ContentProvider:GetAssetFetchStatusChangedSignal(ASSET_ID)
local function onAssetFetchStatusChanged(newAssetFetchStatus: Enum.AssetFetchStatus)
print(`New AssetFetchStatus: {newAssetFetchStatus}`)
end
assetFetchStatusChangedSignal:Connect(onAssetFetchStatusChanged)
-- Trigger the asset to preload
local function onAssetRequestComplete(contentId: string, assetFetchStatus: Enum.AssetFetchStatus)
print(`Preload status {contentId}: {assetFetchStatus.Name}`)
end
ContentProvider:PreloadAsync({ exampleAsset }, onAssetRequestComplete)

GetAssetFetchStatusChangedSignal

A signal that fires when the Enum.AssetFetchStatus of the provided content changes. Connect to this signal by using a callback with one argument of type Enum.AssetFetchStatus. This is particularly useful for assets that might update themselves automatically like the thumbnail of a user when they change clothes.

Parameters

contentId: Content

Returns

Code Samples

Monitoring AssetFetchStatus

local ContentProvider = game:GetService("ContentProvider")
-- An example asset to load
local ASSET_ID = "rbxassetid://9120386436"
local exampleAsset = Instance.new("Sound")
exampleAsset.SoundId = ASSET_ID
-- Output the current AssetFetchStatus of the asset
local initialAssetFetchStatus = ContentProvider:GetAssetFetchStatus(ASSET_ID)
print("Initial AssetFetchStatus:", initialAssetFetchStatus)
-- Listen for updates
local assetFetchStatusChangedSignal = ContentProvider:GetAssetFetchStatusChangedSignal(ASSET_ID)
local function onAssetFetchStatusChanged(newAssetFetchStatus: Enum.AssetFetchStatus)
print(`New AssetFetchStatus: {newAssetFetchStatus}`)
end
assetFetchStatusChangedSignal:Connect(onAssetFetchStatusChanged)
-- Trigger the asset to preload
local function onAssetRequestComplete(contentId: string, assetFetchStatus: Enum.AssetFetchStatus)
print(`Preload status {contentId}: {assetFetchStatus.Name}`)
end
ContentProvider:PreloadAsync({ exampleAsset }, onAssetRequestComplete)

ListEncryptedAssets


Returns

RegisterDefaultEncryptionKey

void

Parameters

encryptionKey: string

Returns

void

RegisterDefaultSessionKey

void

Parameters

sessionKey: string

Returns

void

RegisterEncryptedAsset

void

Parameters

assetId: Content
encryptionKey: string

Returns

void

RegisterSessionEncryptedAsset

void

Parameters

contentId: Content
sessionKey: string

Returns

void

UnregisterDefaultEncryptionKey

void

Returns

void

UnregisterEncryptedAsset

void

Parameters

assetId: Content

Returns

void

PreloadAsync

void
yields

Yields until all of the assets associated with the given Instances have loaded. This can be used to pause a script and not use content until it is certain that the content has been loaded into the experience.

When called, the engine identifies links to content for each item in the list. For any of the Instances which have properties that define links to content, such as a Decal or a Sound, the engine attempts to load these assets from Roblox. For each requested asset, the callback function runs, indicating the asset's final Enum.AssetFetchStatus.

This method can also take in a list of content ID strings, however these strings must correspond to image assets. Attempting to load non-image assets through the use of their content ID strings will result in failure.

If any of the assets fail to load, an error message appears in the output. The method itself will not error and it will continue executing until it has processed each requested instance or asset ID.

Parameters

contentIdList: Array

An array of instances or content ID strings (for images) to load.

callbackFunction: function

The function called when each asset request completes. Returns the content string and the asset's final Enum.AssetFetchStatus.

Default Value: "nil"

Returns

void

Code Samples

Preloading Assets

local ContentProvider = game:GetService("ContentProvider")
local sound = Instance.new("Sound")
sound.SoundId = "rbxassetid://9120386436"
local decal = Instance.new("Decal")
decal.Texture = "rbxassetid://5447528495"
local assets = {
decal,
sound,
}
-- This will be hit as each asset resolves
local callback = function(assetId, assetFetchStatus)
print("PreloadAsync() resolved asset ID:", assetId)
print("PreloadAsync() final AssetFetchStatus:", assetFetchStatus)
end
-- Preload the content and time it
local startTime = os.clock()
ContentProvider:PreloadAsync(assets, callback)
local deltaTime = os.clock() - startTime
print(("Preloading complete, took %.2f seconds"):format(deltaTime))

Events

AssetFetchFailed

Parameters

assetId: Content