# 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/index.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: |
          The ID of the content to monitor for fetch status changes.
    returns:
      - type: RBXScriptSignal
        summary: |
          An `Datatype.RBXScriptSignal` that fires when the
          `Enum.AssetFetchStatus` of the given content changes.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: ContentProvider:ListEncryptedAssets
    summary: |
      Returns an array of the asset IDs that currently have a registered
      encryption key.
    description: |
      Returns an array containing every asset ID that currently has an
      encryption key registered on this `Class.ContentProvider`, whether the key
      was registered directly through
      `Class.ContentProvider:RegisterEncryptedAsset()|RegisterEncryptedAsset()`
      or through
      `Class.ContentProvider:RegisterSessionEncryptedAsset()|RegisterSessionEncryptedAsset()`.

      The default key set through
      `Class.ContentProvider:RegisterDefaultEncryptionKey()|RegisterDefaultEncryptionKey()`
      is not included, because it isn't associated with any specific asset.
    code_samples: []
    parameters: []
    returns:
      - type: Array
        summary: |
          An array of the asset IDs that currently have an encryption key
          registered on this `Class.ContentProvider`.
    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: |
          The content URL of the asset to preload.
    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.

      If PreloadAsync is called on `Class.Instance|Instances` that are not
      currently visible, such as a `Class.Decal` or an `Class.ImageLabel`, the
      Engine will download and store textures used by those Instances in its
      disk cache. Because the `Class.Instance|Instances` are not visible in
      these cases, the Engine may reduce memory consumption by unloading the
      textures after preloading them.
    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: |
      Registers a fallback encryption key used to decrypt any encrypted asset
      that doesn't have its own key registered.
    description: |
      Sets a fallback encryption key that the `Class.ContentProvider` uses to
      decrypt any encrypted asset that isn't matched by a key registered for a
      specific asset through
      `Class.ContentProvider:RegisterEncryptedAsset()|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.
    code_samples: []
    parameters:
      - name: encryptionKey
        type: string
        default:
        summary: |
          The key to use as the default for decrypting encrypted assets.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: ContentProvider:RegisterDefaultSessionKey
    summary: |
      Decrypts the provided session key and registers the result as the default
      encryption key.
    description: |
      Decrypts `sessionKey` using the session's cryptographic context and then
      registers the decrypted result as the default encryption key, exactly as
      `Class.ContentProvider:RegisterDefaultEncryptionKey()|RegisterDefaultEncryptionKey()`
      does. Use this variant when the key is delivered to the client in
      session-encrypted form rather than as plaintext.
    code_samples: []
    parameters:
      - name: sessionKey
        type: string
        default:
        summary: |
          The session-encrypted key to decrypt and register as the default
          encryption key.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: ContentProvider:RegisterEncryptedAsset
    summary: |
      Registers an encryption key used to decrypt a specific encrypted asset.
    description: |
      Associates `encryptionKey` with the given `assetId` so that, when the
      `Class.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
      `Class.ContentProvider:RegisterDefaultEncryptionKey()|RegisterDefaultEncryptionKey()`.
      The method throws an error if `assetId` isn't a valid asset ID.
    code_samples: []
    parameters:
      - name: assetId
        type: ContentId
        default:
        summary: |
          The asset to associate the encryption key with.
      - name: encryptionKey
        type: string
        default:
        summary: |
          The key used to decrypt the specified asset.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: ContentProvider:RegisterSessionEncryptedAsset
    summary: |
      Decrypts the provided session key and registers it as the encryption key
      for a specific asset.
    description: |
      Decrypts `sessionKey` using the session's cryptographic context and then
      registers the decrypted result as the encryption key for `contentId`,
      exactly as
      `Class.ContentProvider:RegisterEncryptedAsset()|RegisterEncryptedAsset()`
      does. Use this variant when the per-asset key is delivered to the client
      in session-encrypted form rather than as plaintext.
    code_samples: []
    parameters:
      - name: contentId
        type: ContentId
        default:
        summary: |
          The asset to associate the decrypted key with.
      - name: sessionKey
        type: string
        default:
        summary: |
          The session-encrypted key to decrypt and register for the specified
          asset.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: ContentProvider:UnregisterDefaultEncryptionKey
    summary: |
      Clears the default encryption key previously set on the
      `Class.ContentProvider`.
    description: |
      Removes the default encryption key registered through
      `Class.ContentProvider:RegisterDefaultEncryptionKey()|RegisterDefaultEncryptionKey()`,
      so that assets without a specifically registered key are no longer
      decrypted with a fallback key. Keys registered for individual assets
      through
      `Class.ContentProvider:RegisterEncryptedAsset()|RegisterEncryptedAsset()`
      are unaffected.
    code_samples: []
    parameters: []
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
  - name: ContentProvider:UnregisterEncryptedAsset
    summary: |
      Removes the encryption key registered for a specific asset.
    description: |
      Removes the encryption key associated with `assetId` by
      `Class.ContentProvider:RegisterEncryptedAsset()|RegisterEncryptedAsset()`,
      so the asset is no longer decrypted with that key. If no key is registered
      for the asset, the call has no effect.
    code_samples: []
    parameters:
      - name: assetId
        type: ContentId
        default:
        summary: |
          The asset whose registered encryption key should be removed.
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - AssetManagement
events:
  - name: ContentProvider.AssetFetchFailed
    summary: |
      Fires when the `Class.ContentProvider` fails to fetch an asset, passing
      the asset's ID.
    description: |
      Fires when an asset requested through the `Class.ContentProvider` fails to
      be fetched, passing the content ID of the asset that failed.
    code_samples: []
    parameters:
      - name: assetId
        type: ContentId
        default:
        summary: |
          The content ID of the asset that failed to load.
    tags: []
    deprecation_message: ''
    security: None
    capabilities:
      - AssetManagement
callbacks: []