Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.
ContentProvider
Inherits from: Instance → Object
Service that loads content (assets) into a game.
Roblox servers stream all assets to the client at runtime: objects in the Workspace, mesh assets, texture assets, etc. Assets such as mesh visual data, textures, decals, and sounds are streamed in as required, regardless of whether Streaming is enabled.
In some cases, this behavior is undesirable, as it can lead to a delay before the content loads into the experience.
ContentProvider lets you preload assets into an experience using the ContentProvider:PreloadAsync() method. You might want to display a loading screen, preload critical assets, and only then allow the player into the experience.
Best Practices for Preloading
- Only preload essential assets, not the entire
Workspace. You might get occasional pop-in, but it decreases load times and generally doesn't disrupt the player experience. Assets that are good candidates for preloading include those required for the loading screen, the UI, or the starting area. - Let players skip the loading screen, or automatically skip it after a certain amount of time.
Inherits from: Instance
Memory category: Instances
Tags: NotCreatable, Service, NotReplicated
Code samples: View on Creator Hub (ContentProvider1).
Properties
| Name | Type / Returns | Description |
|---|---|---|
| ContentProvider.BaseUrl | string | Used by the ContentProvider to download assets from the Roblox website. |
| ContentProvider.RequestQueueSize | int | Gives the number of items in the ContentProvider request queue that need to be downloaded. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.Archivable | boolean | Determines if an Instance and its descendants can be cloned using Instance:Clone(), and can be saved/published. |
| Instance.archivable | boolean | |
| Instance.Capabilities | SecurityCapabilities | The set of capabilities allowed to be used for scripts inside this container. |
| Instance.IsInSandbox | boolean | Indicates whether the instance is inside a sandboxed container. |
| Instance.Name | string | A non-unique identifier of the Instance. |
| Instance.Parent | Instance | Determines the hierarchical parent of the Instance. |
| Instance.PredictionMode | PredictionMode | Reflects the client-side prediction mode applied to the instance under server-authoritative physics. |
| Instance.RobloxLocked | boolean | A deprecated property that used to protect CoreGui objects. |
| Instance.Sandboxed | boolean | When enabled, the instance can only access abilities in its Capabilities list. |
| Instance.UniqueId | UniqueId | A unique identifier for the instance. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.ClassName | string | A read-only string representing the class this Object belongs to. |
| Object.className | string |
ContentProvider.BaseUrl
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.
| Field | Value |
|---|---|
| type | string |
| tags | ["ReadOnly","NotReplicated"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Data |
| serialization | {"can_load":false,"can_save":true} |
| capabilities | ["AssetManagement"] |
ContentProvider.RequestQueueSize
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).
| Field | Value |
|---|---|
| type | int |
| tags | ["ReadOnly","NotReplicated"] |
| security | {"read":"None","write":"None"} |
| thread safety | ReadSafe |
| category | Data |
| serialization | {"can_load":false,"can_save":true} |
| capabilities | ["AssetManagement"] |
Code samples: View on Creator Hub (ContentProvider-Loading-Bar).
Methods
| Name | Type / Returns | Description |
|---|---|---|
| ContentProvider:GetAssetFetchStatus | AssetFetchStatus | Gets the current AssetFetchStatus of the contentId provided. |
| ContentProvider:GetAssetFetchStatusChangedSignal | RBXScriptSignal | A signal that fires when the AssetFetchStatus of the provided content changes. |
| ContentProvider:ListEncryptedAssets | Array | Returns an array of the asset IDs that currently have a registered encryption key. |
| ContentProvider:Preload | () | Queues an asset to be downloaded by the ContentProvider. |
| ContentProvider:PreloadAsync | () | Yields until all of the assets associated with the given Instances have loaded. |
| ContentProvider:RegisterDefaultEncryptionKey | () | Registers a fallback encryption key used to decrypt any encrypted asset that doesn't have its own key registered. |
| ContentProvider:RegisterDefaultSessionKey | () | Decrypts the provided session key and registers the result as the default encryption key. |
| ContentProvider:RegisterEncryptedAsset | () | Registers an encryption key used to decrypt a specific encrypted asset. |
| ContentProvider:RegisterSessionEncryptedAsset | () | Decrypts the provided session key and registers it as the encryption key for a specific asset. |
| ContentProvider:UnregisterDefaultEncryptionKey | () | Clears the default encryption key previously set on the ContentProvider. |
| ContentProvider:UnregisterEncryptedAsset | () | Removes the encryption key registered for a specific asset. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance:AddTag | () | Applies a tag to the instance. |
| Instance:children | Instances | Returns an array of the object's children. |
| Instance:ClearAllChildren | () | This method destroys all of an instance's children. |
| Instance:Clone | Instance | Create a copy of an instance and all its descendants, ignoring instances that are not Archivable. |
| Instance:clone | Instance | |
| Instance:Destroy | () | Sets the Instance.Parent property to nil, locks the Instance.Parent property, disconnects all connections, and calls Destroy() on all children. |
| Instance:destroy | () | |
| Instance:FindFirstAncestor | Instance? | Returns the first ancestor of the Instance whose Instance.Name is equal to the given name. |
| Instance:FindFirstAncestorOfClass | Instance? | Returns the first ancestor of the Instance whose Object.ClassName is equal to the given className. |
| Instance:FindFirstAncestorWhichIsA | Instance? | Returns the first ancestor of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstChild | Instance? | Returns the first child of the Instance found with the given name. |
| Instance:findFirstChild | Instance | |
| Instance:FindFirstChildOfClass | Instance? | Returns the first child of the Instance whose ClassName is equal to the given class name. |
| Instance:FindFirstChildWhichIsA | Instance? | Returns the first child of the Instance for whom Object:IsA() returns true for the given className. |
| Instance:FindFirstDescendant | Instance? | Returns the first descendant found with the given Instance.Name. |
| Instance:GetActor | Actor? | Returns the Actor associated with the Instance, if any. |
| Instance:GetAttribute | Variant | Returns the value which has been assigned to the given attribute name. |
| Instance:GetAttributeChangedSignal | RBXScriptSignal | Returns an event that fires when the given attribute changes. |
| Instance:GetAttributes | Dictionary | Returns a dictionary of the instance's attributes. |
| Instance:GetChildren | Instances | Returns an array containing all of the instance's children. |
| Instance:getChildren | Instances | |
| Instance:GetDebugId | string | Returns a coded string of the debug ID used internally by Roblox. |
| Instance:GetDescendants | Instances | Returns an array containing all of the descendants of the instance. |
| Instance:GetFullName | string | Returns a string describing the instance's ancestry. |
| Instance:GetStyled | Variant | Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified. |
| Instance:GetStyledPropertyChangedSignal | RBXScriptSignal | Returns an event that fires when the given style property changes on the instance. |
| Instance:GetTags | Array | Gets an array of all tags applied to the instance. |
| Instance:HasTag | boolean | Check whether the instance has a given tag. |
| Instance:IsAncestorOf | boolean | Returns true if an Instance is an ancestor of the given descendant. |
| Instance:IsDescendantOf | boolean | Returns true if an Instance is a descendant of the given ancestor. |
| Instance:isDescendantOf | boolean | |
| Instance:IsPropertyModified | boolean | Returns true if the value stored in the specified property is not equal to the code-instantiated default. |
| Instance:QueryDescendants | Instances | Returns an array containing all descendants of the instance that match the selector string. |
| Instance:Remove | () | Sets the object's Parent to nil, and does the same for all its descendants. |
| Instance:remove | () | |
| Instance:RemoveTag | () | Removes a tag from the instance. |
| Instance:ResetPropertyToDefault | () | Resets a property to its default value. |
| Instance:SetAttribute | () | Sets the attribute with the given name to the given value. |
| Instance:WaitForChild | Instance | Returns the child of the Instance with the given name. If the child does not exist, it will yield the current thread until it does. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object:GetPropertyChangedSignal | RBXScriptSignal | Get an event that fires when a given property of the object changes. |
| Object:IsA | boolean | Returns true if an object's class matches or inherits from a given class. |
| Object:isA | boolean |
ContentProvider:GetAssetFetchStatus
Gets the current AssetFetchStatus of the contentId provided. Use GetAssetFetchStatusChangedSignal() to listen for changes to this value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| contentId | ContentId | The ID of the content to fetch the status for. |
Returns
| Type | Description |
|---|---|
| AssetFetchStatus | The AssetFetchStatus of the content. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
Code samples: View on Creator Hub (ContentProvider-GetAssetFetchStatus1).
ContentProvider:GetAssetFetchStatusChangedSignal
A signal that fires when the AssetFetchStatus of the provided content changes. Connect to this signal by using a callback with one argument of type AssetFetchStatus. This is particularly useful for assets that might update themselves automatically like the thumbnail of a user when they change clothes.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| contentId | ContentId | The ID of the content to monitor for fetch status changes. |
Returns
| Type | Description |
|---|---|
| RBXScriptSignal | An RBXScriptSignal that fires when the AssetFetchStatus of the given content changes. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
Code samples: View on Creator Hub (ContentProvider-GetAssetFetchStatus1).
ContentProvider:ListEncryptedAssets
Returns an array containing every asset ID that currently has an encryption key registered on this ContentProvider, whether the key was registered directly through RegisterEncryptedAsset() or through RegisterSessionEncryptedAsset().
The default key set through RegisterDefaultEncryptionKey() is not included, because it isn't associated with any specific asset.
Returns
| Type | Description |
|---|---|
| Array | An array of the asset IDs that currently have an encryption key registered on this ContentProvider. |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
ContentProvider:Preload
Deprecated. This item has been superseded by ContentProvider:PreloadAsync() which should be used in all new work.
Usually, content is loaded only when it starts being used. That explains why it often takes a moment for an image to appear in a GuiObject, or a Mesh|mesh to appear in a part, or why a sound doesn't play for the first time. All because the asset has not yet finished loading. Preload is used to load this content beforehand, so that it works instantly.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| contentId | ContentId | The content URL of the asset to preload. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| tags | ["Deprecated"] |
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
Code samples: View on Creator Hub (ContentProvider-Preload1).
ContentProvider:PreloadAsync
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 AssetFetchStatus.
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.
Limitations
SurfaceAppearance and MaterialVariant are not supported by PreloadAsync() because these objects rely on processed texture pack assets rather than directly loading individual textures. Calling it on a SurfaceAppearance instance will not do anything, but the associated textures will still be streamed in during runtime.
If PreloadAsync is called on Instances that are not currently visible, such as a Decal or an ImageLabel, the Engine will download and store textures used by those Instances in its disk cache. Because the Instances are not visible in these cases, the Engine may reduce memory consumption by unloading the textures after preloading them.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| contentIdList | Array | An array of instances to load. | |
| callbackFunction | Function | nil | The function called when each asset request completes. Returns the content string and the asset's final AssetFetchStatus. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| tags | ["Yields"] |
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
Code samples: View on Creator Hub (ContentProvider-PreloadAsync1).
ContentProvider:RegisterDefaultEncryptionKey
Sets a fallback encryption key that the ContentProvider uses to decrypt any encrypted asset that isn't matched by a key registered for a specific asset through RegisterEncryptedAsset(). When an asset is fetched, the engine first looks for a key registered for that asset's ID; if none exists, it falls back to this default key.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| encryptionKey | string | The key to use as the default for decrypting encrypted assets. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
ContentProvider:RegisterDefaultSessionKey
Decrypts sessionKey using the session's cryptographic context and then registers the decrypted result as the default encryption key, exactly as RegisterDefaultEncryptionKey() does. Use this variant when the key is delivered to the client in session-encrypted form rather than as plaintext.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| sessionKey | string | The session-encrypted key to decrypt and register as the default encryption key. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
ContentProvider:RegisterEncryptedAsset
Associates encryptionKey with the given assetId so that, when the ContentProvider fetches that asset, it uses the key to decrypt the downloaded file. A key registered for a specific asset takes precedence over the default key set through RegisterDefaultEncryptionKey(). The method throws an error if assetId isn't a valid asset ID.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| assetId | ContentId | The asset to associate the encryption key with. | |
| encryptionKey | string | The key used to decrypt the specified asset. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
ContentProvider:RegisterSessionEncryptedAsset
Decrypts sessionKey using the session's cryptographic context and then registers the decrypted result as the encryption key for contentId, exactly as RegisterEncryptedAsset() does. Use this variant when the per-asset key is delivered to the client in session-encrypted form rather than as plaintext.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| contentId | ContentId | The asset to associate the decrypted key with. | |
| sessionKey | string | The session-encrypted key to decrypt and register for the specified asset. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
ContentProvider:UnregisterDefaultEncryptionKey
Removes the default encryption key registered through RegisterDefaultEncryptionKey(), so that assets without a specifically registered key are no longer decrypted with a fallback key. Keys registered for individual assets through RegisterEncryptedAsset() are unaffected.
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
ContentProvider:UnregisterEncryptedAsset
Removes the encryption key associated with assetId by RegisterEncryptedAsset(), so the asset is no longer decrypted with that key. If no key is registered for the asset, the call has no effect.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| assetId | ContentId | The asset whose registered encryption key should be removed. |
Returns
| Type | Description |
|---|---|
| () |
| Field | Value |
|---|---|
| security | None |
| thread safety | Unsafe |
| capabilities | ["AssetManagement"] |
Events
| Name | Type / Returns | Description |
|---|---|---|
| ContentProvider.AssetFetchFailed | Fires when the ContentProvider fails to fetch an asset, passing the asset's ID. |
Inherited from Instance
| Name | Type / Returns | Description |
|---|---|---|
| Instance.AncestryChanged | Fires when the Instance.Parent property of this object or one of its ancestors is changed. | |
| Instance.AttributeChanged | Fires whenever an attribute is changed on the Instance. | |
| Instance.ChildAdded | Fires after an object is parented to this Instance. | |
| Instance.childAdded | ||
| Instance.ChildRemoved | Fires after a child is removed from this Instance. | |
| Instance.DescendantAdded | Fires after a descendant is added to the Instance. | |
| Instance.DescendantRemoving | Fires immediately before a descendant of the Instance is removed. | |
| Instance.Destroying | Fires immediately before (or is deferred until after) the instance is destroyed via Instance:Destroy(). | |
| Instance.StyledPropertiesChanged | Fires whenever any style property is changed on the instance, including when a property is set to nil. |
Inherited from Object
| Name | Type / Returns | Description |
|---|---|---|
| Object.Changed | Fires immediately after a property of the object changes, with some limitations. |
ContentProvider.AssetFetchFailed
Fires when an asset requested through the ContentProvider fails to be fetched, passing the content ID of the asset that failed.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
| assetId | ContentId | The content ID of the asset that failed to load. |
| Field | Value |
|---|---|
| security | None |
| capabilities | ["AssetManagement"] |