预加载资源

预加载资源可让资产在场景启动时就被下载，从而在玩家第一次交互时即可立即使用。

在某些情况下，资源会被添加到场景中，但不会立即使用。例如，音频文件可能只会在玩家按下按钮时播放。在这种情况下，玩家第一次按下按钮时，音频可能会晚几秒播放，因为文件只有在需要时才会下载。

为避免此问题，请使用 AssetLoad 组件，确保这些资源在需要之前已下载并可供使用。

import { AssetLoad } from "@dcl/sdk/ecs"

AssetLoad.create(engine.RootEntity, {
  assets: [
    "assets/scene/bundle1/explosionSound.mp3",
    "assets/scene/bundle1/explosion.glb",
  ],
})

列在 AssetLoad 组件中的资源会被下载并加入内存，确保场景需要加载它们时可立即使用。

一些重要注意事项：

• 你可以将 AssetLoad 组件放在任何实体上（不仅仅是 RootEntity），并且可以根据需要在多个实体上使用它。这对于处理场景中不同层级或区域的独立加载状态很有帮助。

• 该 AssetLoad 组件用于将资源添加到内存中，而不是移除它们。将资源从 AssetLoad.create 中移除不会释放内存。

• 如果某个资源在场景加载时会立即使用（例如，放置在场景中的 GLB 模型，或持续播放的背景音效），则无需使用 AssetLoad 组件，因为它已经在下载中了。

• 向 AssetLoad.create添加资源时请注意，只预加载在场景启动时不需要的资源，以避免不必要的性能开销。

• 你只能预加载作为场景文件一部分上传的资源。此功能无法用于预加载来自外部 URL 的图片

响应加载状态

如果你的场景能够对每个资源何时完成下载做出响应，那么预加载资源会更有用。例如，你可能希望一直显示加载界面，直到所有资源都准备就绪，向玩家显示进度，或者优雅地处理某个下载失败的资源。

要跟踪这一点，请使用 assetLoadLoadingStateSystem。调用其 registerAssetLoadLoadingStateEntity 方法，并传入持有 AssetLoad 组件的实体以及一个回调函数。每当该实体某个资源的加载状态发生变化时，回调函数都会运行。

import {
  AssetLoad,
  LoadingState,
  assetLoadLoadingStateSystem,
} from "@dcl/sdk/ecs"

const preloader = engine.addEntity()
AssetLoad.create(preloader, {
  assets: [
    "assets/scene/bundle1/explosionSound.mp3",
    "assets/scene/bundle1/explosion.glb",
  ],
})

assetLoadLoadingStateSystem.registerAssetLoadLoadingStateEntity(
  preloader,
  (assetLoadState) => {
    console.log(
      `Asset ${assetLoadState.asset} is now: ${assetLoadState.currentState}`
    )
  }
)

回调函数会接收一个包含以下属性的对象：

• asset：状态发生变化的资源路径。这与您在 AssetLoad 组件。

• currentState来自 LoadingState 枚举中的值，用于描述该资源的新状态。

该 LoadingState 枚举可以包含以下值：

• LoadingState.LOADING：资源正在下载中。

• LoadingState.FINISHED：资源已成功下载并可供使用。

• LoadingState.FINISHED_WITH_ERROR：找到了该资源，但在下载时发生了错误。

• LoadingState.NOT_FOUND：在提供的路径下未找到任何资源。

• LoadingState.UNKNOWN：资源状态未知。

以下示例使用加载状态，根据资源预加载的进度来改变实体的颜色：

import {
  AssetLoad,
  LoadingState,
  Material、
  assetLoadLoadingStateSystem,
} from "@dcl/sdk/ecs"
import { Color4 } from "@dcl/sdk/math"

function getLoadingColor(state: LoadingState): Color4 {
  switch (state) {
    case LoadingState.FINISHED:
      return Color4.Green()
    case LoadingState.LOADING:
      return Color4.Yellow()
    case LoadingState.FINISHED_WITH_ERROR:
    case LoadingState.NOT_FOUND:
      return Color4.Red()
    default:
      return Color4.Gray()
  }
}

assetLoadLoadingStateSystem.registerAssetLoadLoadingStateEntity(
  preloader,
  (assetLoadState) => {
    Material.setPbrMaterial(myEntity, {
      albedoColor: getLoadingColor(assetLoadState.currentState),
    })
  }
)

💡 提示：你可以向现有的 AssetLoad 组件中添加更多资源，例如在响应玩家操作时。使用 AssetLoad.getOrCreateMutable() 来获取该组件，并将新的路径推入其 assets 数组中。注册的回调函数也会在这些新添加的资源下载时触发。

💡 提示：关于此组件的可运行示例，请参见 88,-12-asset-load 测试场景，它通过一个预加载 mp3、纹理、视频和 glb 的 AssetLoad 组件，并通过其报告每个资源的状态 assetLoadLoadingStateSystem ——其中包括一个故意缺失的路径，其解析结果为 NOT_FOUND.