> 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-pt/scenes-sdk7/otimizacao/pre-load-resources.md).

# Pré-carregar Recursos

Pré-carregar Resources permite que assets sejam baixados no início da scene para estarem prontos quando o player interagir com eles pela primeira vez.

Em alguns casos, um asset é adicionado à scene, mas não é usado imediatamente. Por exemplo, um arquivo de som pode ser reproduzido apenas quando o player pressiona um button. Nesse cenário, na primeira vez que o player pressiona o button, o áudio pode tocar com alguns segundos de atraso, porque o arquivo só é baixado quando necessário.

Para evitar esse problema, use o `AssetLoad` component para garantir que esses assets sejam baixados e estejam prontos para uso antes de serem necessários.

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

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

Os assets listados no `AssetLoad` component são baixados e adicionados à memória, garantindo que estejam instantaneamente disponíveis quando a scene precisar carregá-los.

Algumas considerações importantes:

* Você pode colocar o `AssetLoad` component em qualquer entity (não apenas no RootEntity), e pode usá-lo em quantas entities forem necessárias. Isso pode ser útil para lidar com estados de carregamento separados para diferentes níveis ou regiões da sua scene.
* A `AssetLoad` component é usado para adicionar assets à memória, não para removê-los. Remover um asset da lista em `AssetLoad.create` não liberará memória.
* Se um asset for usado imediatamente quando a scene carregar (por exemplo, um modelo GLB colocado na scene, ou um som de fundo que toca continuamente), não há necessidade de usar o `AssetLoad` component, já que ele já está sendo baixado.
* Tenha cuidado ao adicionar assets a `AssetLoad.create`, e faça pré-carregamento apenas dos assets que não sejam necessários no início da scene para evitar custos desnecessários de desempenho.
* Você só pode pré-carregar assets que foram enviados como parte dos arquivos da scene. Esse recurso não funcionará para pré-carregar imagens de um URL externo

## Reagindo ao estado de carregamento

Pré-carregar assets é mais útil se a sua scene puder reagir quando cada asset terminar de baixar. Por exemplo, talvez você queira manter uma tela de carregamento até que todos os assets estejam prontos, mostrar o progresso ao player ou lidar de forma elegante com um asset que falhou ao baixar.

Para acompanhar isso, use o `assetLoadLoadingStateSystem`. Chame o seu `registerAssetLoadLoadingStateEntity` método, passando a entity que contém o `AssetLoad` component e uma função callback. O callback é executado toda vez que o estado de carregamento de um dos assets dessa entity muda.

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

O callback recebe um objeto com as seguintes propriedades:

* `asset`: O caminho do asset cujo estado mudou. Isso corresponde a uma das strings que você listou no `AssetLoad` component.
* `currentState`: Um valor do `LoadingState` enum, descrevendo o novo estado desse asset.

A `LoadingState` enum pode conter os seguintes valores:

* `LoadingState.LOADING`: O asset está sendo baixado no momento.
* `LoadingState.FINISHED`: O asset terminou de baixar com sucesso e está pronto para uso.
* `LoadingState.FINISHED_WITH_ERROR`: O asset foi encontrado, mas ocorreu um erro ao baixá-lo.
* `LoadingState.NOT_FOUND`: Nenhum asset foi encontrado no caminho fornecido.
* `LoadingState.UNKNOWN`: O estado do asset não é conhecido.

O exemplo a seguir usa o estado de carregamento para mudar a cor de uma entity dependendo de como o seu pré-carregamento está progredindo:

```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" %}
**💡 Dica**: Você pode adicionar mais assets a um `AssetLoad` component existente depois de criá-lo, por exemplo em resposta a uma ação do player. Use `AssetLoad.getOrCreateMutable()` para obter o component e adicionar novos paths ao seu array de `assets` . O callback registrado também será executado para esses assets recém-adicionados à medida que forem baixados.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para um exemplo funcional desse component, veja a [`88,-12-asset-load`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-12-asset-load) scene de teste, que pré-carrega um mp3, uma textura, um vídeo e um glb por meio de um `AssetLoad` component e informa o estado de cada asset por meio de `assetLoadLoadingStateSystem` — incluindo um caminho intencionalmente ausente que é resolvido 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.