ContentProvider¶
Service that is used to load content, or assets, into a game.
Description¶
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.
Inheritance¶
Object → Instance → ContentProvider
Nova inheritance: Instance → ContentProvider
Properties¶
BaseUrl Supported Property Used by the ContentProvider to download assets from the Roblox website.
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 Supported Property Gives the number of items in the ContentProvider request queue that need to be downloaded.
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).
Methods¶
Preload Supported Function Deprecated Queues an asset to be downloaded by the ContentProvider.
Queues an asset to be downloaded by the ContentProvider.
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.
PreloadAsync Supported Function Yields until all of the assets associated with the given Instances have loaded.
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.
Roblox reference signature
SetAssetUrl Supported Function
No description available.
LocalUserSecuritySetBaseUrl Supported Function
No description available.
LocalUserSecuritySetCacheSize Supported Function
No description available.
LocalUserSecuritySetThreadPool Supported Function
No description available.
LocalUserSecurityInherited members¶
Inherited from Instance: 8 properties, 36 methods, 7 events. They are documented on the base class page.
13 modern Roblox member(s) are not implemented yet — expand to inspect
Members declared by Roblox's ContentProvider class (or by a missing base class) that Nova does not expose. Use this list to scope a migration; the compatibility guide has the recommended workaround.
Methods¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
GetAssetFetchStatus |
ContentProvider:GetAssetFetchStatus(contentId: ContentId): AssetFetchStatus |
Not yet | Gets the current AssetFetchStatus of the contentId provided. |
— |
GetAssetFetchStatusChangedSignal |
ContentProvider:GetAssetFetchStatusChangedSignal(contentId: ContentId): RBXScriptSignal |
Not yet | A signal that fires when the AssetFetchStatus of the provided content changes. | — |
GetDependencyContentIds |
ContentProvider:GetDependencyContentIds(root: Instance): Array |
Not yet | — | RobloxScriptSecurity |
GetDetailedFailedRequests |
ContentProvider:GetDetailedFailedRequests(): Array |
Not yet | — | RobloxScriptSecurity |
GetFailedRequests |
ContentProvider:GetFailedRequests(): Array |
Not yet | — | RobloxScriptSecurity |
ListEncryptedAssets |
ContentProvider:ListEncryptedAssets(): Array |
Not yet | Returns an array of the asset IDs that currently have a registered encryption key. | — |
RegisterDefaultEncryptionKey |
ContentProvider:RegisterDefaultEncryptionKey(encryptionKey: string): null |
Not yet | Registers a fallback encryption key used to decrypt any encrypted asset that doesn't have its own key registered. | — |
RegisterDefaultSessionKey |
ContentProvider:RegisterDefaultSessionKey(sessionKey: string): null |
Not yet | Decrypts the provided session key and registers the result as the default encryption key. | — |
RegisterEncryptedAsset |
ContentProvider:RegisterEncryptedAsset(assetId: ContentId, encryptionKey: string): null |
Not yet | Registers an encryption key used to decrypt a specific encrypted asset. | — |
RegisterSessionEncryptedAsset |
ContentProvider:RegisterSessionEncryptedAsset(contentId: ContentId, sessionKey: string): null |
Not yet | Decrypts the provided session key and registers it as the encryption key for a specific asset. | — |
UnregisterDefaultEncryptionKey |
ContentProvider:UnregisterDefaultEncryptionKey(): null |
Not yet | Clears the default encryption key previously set on the ContentProvider. | — |
UnregisterEncryptedAsset |
ContentProvider:UnregisterEncryptedAsset(assetId: ContentId): null |
Not yet | Removes the encryption key registered for a specific asset. | — |
Events¶
| Member | Signature | Status | Notes | Flags |
|---|---|---|---|---|
AssetFetchFailed |
AssetFetchFailed(assetId: ContentId) |
Not yet | Fires when the ContentProvider fails to fetch an asset, passing the asset's ID. | — |
Roblox reference: ContentProvider
Generated from Nova's API dump and Roblox creator-docs. Nova-only members come from the engine's reflection metadata.