rojo/.cursor/rules/roblox/reference/engine/classes/ContentProvider.yaml

# 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: []