Precargar recursos

Precargar recursos permite que los assets se descarguen al iniciar la escena para que estén listos cuando el jugador interactúe con ellos por primera vez.

En algunos casos, se agrega un asset a la escena, pero no se usa de inmediato. Por ejemplo, un archivo de sonido puede reproducirse solo cuando el jugador presiona un botón. En este escenario, la primera vez que el jugador presiona el botón, el audio puede reproducirse un par de segundos demasiado tarde, porque el archivo solo se descarga cuando se necesita.

Para evitar este problema, usa el AssetLoad component para asegurarte de que estos assets se descarguen y estén listos para usar antes de que se necesiten.

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

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

Los assets enumerados en el AssetLoad component se descargan y se agregan a la memoria, lo que garantiza que estén disponibles al instante cuando la escena necesite cargarlos.

Algunas consideraciones importantes:

• Puedes colocar el AssetLoad component en cualquier entity (no solo en RootEntity), y puedes usarlo en tantas entities como sea necesario. Esto puede ser útil para manejar estados de carga separados para distintos niveles o regiones de tu escena.

• La AssetLoad component se usa para agregar assets a la memoria, no para eliminarlos. Quitar un asset de la lista en AssetLoad.create no liberará memoria.

• Si un asset se usa inmediatamente cuando la escena se carga (por ejemplo, un modelo GLB colocado en la escena o un sonido de fondo que se reproduce continuamente), no hay necesidad de usar el AssetLoad component, ya que ya se está descargando.

• Ten cuidado al agregar assets a AssetLoad.create, y solo precarga assets que no sean necesarios al inicio de la escena para evitar costos de rendimiento innecesarios.

• Solo puedes precargar assets que se hayan subido como parte de los archivos de la escena. Esta función no funcionará para precargar imágenes desde una URL externa

Reaccionar al estado de carga

Precargar assets es más útil si tu escena puede reaccionar cuando cada asset termina de descargarse. Por ejemplo, es posible que quieras mantener una pantalla de carga hasta que cada asset esté listo, mostrar el progreso al jugador o manejar de forma elegante un asset que no pudo descargarse.

Para hacer un seguimiento de esto, usa el assetLoadLoadingStateSystem. Llama a su registerAssetLoadLoadingStateEntity método, pasando la entity que contiene el AssetLoad component y una función de callback. El callback se ejecuta cada vez que cambia el estado de carga de uno de los assets de esa entity.

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} ahora es: ${assetLoadState.currentState}`
    )
  }
)

El callback recibe un objeto con las siguientes propiedades:

• asset: La ruta del asset cuyo estado cambió. Esto coincide con una de las cadenas que enumeraste en el AssetLoad component.

• currentState: Un valor del LoadingState enum, que describe el nuevo estado de ese asset.

La LoadingState enum puede contener los siguientes valores:

• LoadingState.LOADING: El asset se está descargando actualmente.

• LoadingState.FINISHED: El asset terminó de descargarse correctamente y está listo para usar.

• LoadingState.FINISHED_WITH_ERROR: El asset se encontró, pero ocurrió un error al descargarlo.

• LoadingState.NOT_FOUND: No se encontró ningún asset en la ruta proporcionada.

• LoadingState.UNKNOWN: El estado del asset no se conoce.

El siguiente ejemplo usa el estado de carga para cambiar el color de una entity según cómo progresa su precarga:

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),
    })
  }
)

💡 Consejo: Puedes agregar más assets a un AssetLoad component después de crearlo, por ejemplo en respuesta a una acción del jugador. Usa AssetLoad.getOrCreateMutable() para obtener el component y agregar nuevas rutas a su assets array de assets. El callback registrado también se activará para estos assets recién agregados a medida que se descargan.

💡 Consejo: Para ver un ejemplo funcional de este component, consulta la 88,-12-asset-load escena de prueba, que precarga un mp3, una Texture, un video y un glb a través de un AssetLoad component y reporta el estado de cada asset a través de assetLoadLoadingStateSystem — incluyendo una ruta deliberadamente ausente que se resuelve como NOT_FOUND.