> 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 recursos permite que os assets sejam baixados no início da scene para que estejam prontos quando o jogador 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 botão. Nesse cenário, na primeira vez que o player pressiona o botão, 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 na RootEntity), e você 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.
* O `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 carrega (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, pois ele já está sendo baixado.
* Tenha cuidado ao adicionar assets a `AssetLoad.create`, e faça pré-carregamento apenas dos assets que não são necessários no início da scene para evitar custos desnecessários de performance.
* Você só pode fazer pré-carregamento de assets que são enviados como parte dos arquivos da scene. Este recurso não funcionará para fazer pré-carregamento de imagens de uma URL externa

## Reagindo ao estado de carregamento

Fazer pré-carregamento de assets é mais útil se a sua scene puder reagir quando cada asset terminar de baixar. Por exemplo, você pode querer manter uma tela de carregamento até que todos os assets estejam prontos, mostrar progresso ao player ou lidar graciosamente com um asset que falhou ao baixar.

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

```ts
import {
  AssetLoad,
  LoadingState,
  assetLoadLoadingStateSystem,
} de "@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}`
    )
  }
)
```

A 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 em `AssetLoad` component.
* `currentState`: Um valor do `LoadingState` enum, descrevendo o novo estado desse asset.

O `LoadingState` O 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,
} de "@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 existente `AssetLoad` component depois de criá-lo, por exemplo em resposta a uma ação do player. Use `AssetLoad.getOrCreateMutable()` para buscar o component e adicionar novos caminhos ao seu `assets` array. O callback registrado também será disparado para esses assets recém-adicionados enquanto são baixados.
{% endhint %}

{% hint style="info" %}
**💡 Dica**: Para ver um exemplo funcional desse component, consulte a [`88,-12-asset-load`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-12-asset-load) test scene, que faz pré-carregamento de um mp3, uma texture, um video e um glb por meio de um único `AssetLoad` component e informa o estado de cada asset por meio de `assetLoadLoadingStateSystem` — incluindo um caminho ausente propositalmente que resolve para `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-pt/scenes-sdk7/otimizacao/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.