> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/optimizacion/pre-load-resources.md).

# Precargar recursos

La precarga de 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 añade un asset a la escena, pero no se usa de inmediato. Por ejemplo, un archivo de sonido quizá solo se reproduzca cuando el jugador presiona un botón. En este caso, la primera vez que el jugador presione el botón, el audio podría reproducirse un par de segundos 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 usarse antes de que se necesiten.

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

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

Los assets que aparecen en el `AssetLoad` component se descargan y se añaden a la memoria, para que estén disponibles al instante cuando la escena necesite cargarlos.

Algunas consideraciones importantes:

* Puedes colocar el `AssetLoad` component en cualquier entidad (no solo en RootEntity) y puedes usarlo en tantas entidades como sea necesario. Esto puede ser útil para gestionar estados de carga separados para distintos niveles o regiones de la escena.
* **Procura que cada entidad con `AssetLoad` tenga unos 40 paths como máximo.** Divide las listas más largas entre varias entidades. Consulta [Dividir listas largas entre entidades](#split-long-lists-across-entities).
* El `AssetLoad` component se usa para añadir assets a la memoria, no para quitarlos. Quitar un asset de la lista en `AssetLoad.create` no liberará memoria.
* Si un asset se usa inmediatamente al cargar la escena (por ejemplo, un modelo GLB colocado en la escena o un sonido de fondo que se reproduce continuamente), no es necesario usar el `AssetLoad` component, ya que el asset ya se está descargando.
* Ten cuidado al añadir assets a `AssetLoad.create`y precarga solo los assets que no sean necesarios al iniciar la escena para evitar costes de rendimiento innecesarios.
* Solo puedes precargar assets que se hayan subido como parte de los archivos de la escena. Esta función no sirve para precargar imágenes desde una URL externa

## Reaccionar al estado de carga

La precarga de assets resulta más útil si la escena puede reaccionar cuando termina la descarga de cada asset. Por ejemplo, quizá quieras mantener una pantalla de carga hasta que todos los assets estén listos, mostrar el progreso al jugador o gestionar correctamente un asset cuya descarga haya fallado.

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

```ts
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}`
    )
  }
)
```

El callback recibe un objeto con las siguientes propiedades:

* `asset`: El path del asset cuyo state cambió. Coincide con una de las cadenas que enumeraste en el `AssetLoad` component.
* `currentState`: Un valor del enum `LoadingState` que describe el nuevo state de ese asset.

El enum `LoadingState` puede contener los siguientes valores:

* `LoadingState.LOADING`: El asset se está descargando.
* `LoadingState.FINISHED`: El asset se ha descargado correctamente y está listo para usarse.
* `LoadingState.FINISHED_WITH_ERROR`: Se encontró el asset, pero se produjo un error al descargarlo.
* `LoadingState.NOT_FOUND`: No se encontró ningún asset en el path proporcionado.
* `LoadingState.UNKNOWN`: Se desconoce el state del asset.

El siguiente ejemplo usa el state de carga para cambiar el color de una entity según el progreso de su precarga:

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

{% hint style="info" %}
**💡 Consejo**: Puedes añadir más assets a un component `AssetLoad` existente después de crearlo, por ejemplo, en respuesta a una action del jugador. Usa `AssetLoad.getOrCreateMutable()` para obtener el component y añadir nuevos paths a su array `assets` . El callback registrado también se ejecutará para estos assets recién añadidos a medida que se descarguen.
{% endhint %}

### Divide las listas largas entre varias entities

Asigna a cada entity `AssetLoad` un **máximo de 40 paths**. Si una entity supera aproximadamente los 50 assets, su callback deja de ejecutarse y nunca se informa del estado de los assets restantes, sin que se produzca ningún error.

El motivo es un límite estricto en la forma en que se almacenan los estados de carga. El cliente agrega una entrada por cada cambio de estado de cada recurso, normalmente `LOADING` y luego `FINISHED`, a un conjunto que contiene 100 entradas por Entity. Cuando el conjunto se llena, se queda en 100, y el SDK solo llama a tu callback cuando cambia el número de entradas, así que no se procesa nada más.

Para precargar más de 40 recursos, divide la lista en lotes y asigna a cada lote su propia Entity y su propio callback:

```ts
import { AssetLoad, assetLoadLoadingStateSystem, engine } from '@dcl/sdk/ecs'

const allAssets = [
	'assets/models/tree.glb',
	'assets/models/rock.glb',
	// ...a long list
]

// One AssetLoad entity per batch of 40 paths
for (let i = 0; i < allAssets.length; i += 40) {
	const batchEntity = engine.addEntity()
	AssetLoad.create(batchEntity, { assets: allAssets.slice(i, i + 40) })

	assetLoadLoadingStateSystem.registerAssetLoadLoadingStateEntity(batchEntity, (assetLoadState) => {
		console.log(assetLoadState.asset, assetLoadState.currentState)
	})
}
```

{% hint style="info" %}
**💡 Consejo**: Si tu Scene espera a que se carguen todos los recursos antes de iniciarse, añade un límite de tiempo a esa espera y registra las rutas de las que nunca recibiste respuesta. Una lista con nombres es mucho más fácil de depurar que una pantalla de carga que nunca desaparece.
{% endhint %}

{% hint style="info" %}
**💡 Consejo**: Para ver un ejemplo funcional de este componente, consulta la [`88,-12-asset-load`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-12-asset-load) Scene de prueba, que precarga un mp3, una Texture, un Video y un glb mediante un solo componente `AssetLoad` e informa del estado de cada recurso a través de `assetLoadLoadingStateSystem` — incluido una ruta deliberadamente inexistente que se resuelve como `NOT_FOUND`.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/optimizacion/pre-load-resources.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
