# This file is automatically generated. Please don't edit it manually. # To submit a bug report on the content, see # https://devforum.roblox.com/c/bug-reports/documentation-issues/72 name: ContentProvider type: class memory_category: Instances summary: | 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](../../../workspace/streaming.md) 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 `Class.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 `Class.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. code_samples: - ContentProvider1 inherits: - Instance descendants: [] tags: - NotCreatable - Service - NotReplicated deprecation_message: '' properties: - name: ContentProvider.BaseUrl summary: | Used by the `Class.ContentProvider` to download assets from the Roblox website. description: | Used by the `Class.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 `Class.ContentProvider:SetBaseUrl()` function in the command bar; however, this is not recommended and may cause asset loading issues. code_samples: [] type: string tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: true capabilities: - AssetManagement - name: ContentProvider.RequestQueueSize summary: | Gives the number of items in the `Class.ContentProvider` request queue that need to be downloaded. description: | Gives the number of items in the `Class.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 `Class.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 type: int tags: - ReadOnly - NotReplicated deprecation_message: '' security: read: None write: None thread_safety: ReadSafe category: Data serialization: can_load: false can_save: true capabilities: - AssetManagement methods: - name: ContentProvider:GetAssetFetchStatus summary: | Gets the current `Enum.AssetFetchStatus` of the `contentId` provided. description: | Gets the current `Enum.AssetFetchStatus` of the `contentId` provided. Use `Class.ContentProvider:GetAssetFetchStatusChangedSignal()|GetAssetFetchStatusChangedSignal()` to listen for changes to this value. code_samples: - ContentProvider-GetAssetFetchStatus1 parameters: - name: contentId type: ContentId default: summary: | The ID of the content to fetch the status for. returns: - type: AssetFetchStatus summary: | The `Enum.AssetFetchStatus` of the content. tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:GetAssetFetchStatusChangedSignal summary: | A signal that fires when the `Enum.AssetFetchStatus` of the provided content changes. description: | 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. code_samples: - ContentProvider-GetAssetFetchStatus1 parameters: - name: contentId type: ContentId default: summary: '' returns: - type: RBXScriptSignal summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:ListEncryptedAssets summary: '' description: '' code_samples: [] parameters: [] returns: - type: Array summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:Preload summary: | Queues an asset to be downloaded by the `Class.ContentProvider`. description: | 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 `Class.GuiObject`, or a `Mesh|mesh` to appear in a `Class.BasePart|part`, or why a `Class.Sound|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. code_samples: - ContentProvider-Preload1 parameters: - name: contentId type: ContentId default: summary: '' returns: - type: () summary: '' tags: - Deprecated deprecation_message: | This item has been superseded by `Class.ContentProvider:PreloadAsync()` which should be used in all new work. security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:PreloadAsync summary: | Yields until all of the assets associated with the given `Class.Instance|Instances` have loaded. description: | Yields until all of the assets associated with the given `Class.Instance|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 `Class.Instance|Instances` which have properties that define links to content, such as a `Class.Decal|Decal` or a `Class.Sound|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`. 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 `Class.SurfaceAppearance` and `Class.MaterialVariant` are not supported by `Class.ContentProvider:PreloadAsync()|PreloadAsync()` because these objects rely on processed texture pack assets rather than directly loading individual textures. Calling it on a `Class.SurfaceAppearance` instance will not do anything, but the associated textures will still be streamed in during runtime. code_samples: - ContentProvider-PreloadAsync1 parameters: - name: contentIdList type: Array default: summary: | An array of instances to load. - name: callbackFunction type: Function default: nil summary: | The function called when each asset request completes. Returns the `Datatype.Content|content` string and the asset's final `Enum.AssetFetchStatus`. returns: - type: () summary: '' tags: - Yields deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:RegisterDefaultEncryptionKey summary: '' description: '' code_samples: [] parameters: - name: encryptionKey type: string default: summary: '' returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:RegisterDefaultSessionKey summary: '' description: '' code_samples: [] parameters: - name: sessionKey type: string default: summary: '' returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:RegisterEncryptedAsset summary: '' description: '' code_samples: [] parameters: - name: assetId type: ContentId default: summary: '' - name: encryptionKey type: string default: summary: '' returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:RegisterSessionEncryptedAsset summary: '' description: '' code_samples: [] parameters: - name: contentId type: ContentId default: summary: '' - name: sessionKey type: string default: summary: '' returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:UnregisterDefaultEncryptionKey summary: '' description: '' code_samples: [] parameters: [] returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement - name: ContentProvider:UnregisterEncryptedAsset summary: '' description: '' code_samples: [] parameters: - name: assetId type: ContentId default: summary: '' returns: - type: () summary: '' tags: [] deprecation_message: '' security: None thread_safety: Unsafe capabilities: - AssetManagement events: - name: ContentProvider.AssetFetchFailed summary: '' description: '' code_samples: [] parameters: - name: assetId type: ContentId default: summary: '' tags: [] deprecation_message: '' security: None capabilities: - AssetManagement callbacks: []