> 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-ko/sdk7/optimizing/pre-load-resources.md).

# 리소스 미리 불러오기

리소스 미리 불러오기를 사용하면 에셋이 씬 시작 시 다운로드되어 플레이어가 처음 상호작용할 때 이미 준비되어 있습니다.

경우에 따라 자산이 씬에 추가되지만 즉시 사용되지는 않습니다. 예를 들어, 사운드 파일은 플레이어가 버튼을 눌렀을 때만 재생될 수 있습니다. 이런 상황에서는 플레이어가 처음 버튼을 눌렀을 때 파일이 필요할 때만 다운로드되기 때문에 오디오가 몇 초 늦게 재생될 수 있습니다.

이 문제를 피하려면 `AssetLoad` 컴포넌트를 사용하여 이러한 자산이 필요하기 전에 다운로드되고 사용할 준비가 되도록 하세요.

```ts
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` 컴포넌트를 보유한 엔티티와 콜백 함수를 전달하세요. 콜백은 해당 엔티티의 자산 중 하나의 로딩 상태가 바뀔 때마다 실행됩니다.

```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(
      `자산 ${assetLoadState.asset}의 현재 상태: ${assetLoadState.currentState}`
    )
  }
)
```

콜백은 다음 속성을 가진 객체를 받습니다:

* `asset`: 상태가 변경된 자산의 경로입니다. 이는 `AssetLoad` 컴포넌트를 추가해야 합니다.
* `currentState`: `LoadingState` 열거형의 값으로, 해당 자산의 새 상태를 설명합니다.

이 `LoadingState` 열거형은 다음 값을 가질 수 있습니다:

* `LoadingState.LOADING`: 자산이 현재 다운로드 중입니다.
* `LoadingState.FINISHED`: 자산 다운로드가 성공적으로 완료되었으며 사용할 준비가 되었습니다.
* `LoadingState.FINISHED_WITH_ERROR`: 자산을 찾았지만 다운로드하는 동안 오류가 발생했습니다.
* `LoadingState.NOT_FOUND`: 제공된 경로에서 자산을 찾을 수 없습니다.
* `LoadingState.UNKNOWN`: 자산의 상태를 알 수 없습니다.

다음 예시는 로딩 상태를 사용해 사전 로드 진행 상황에 따라 엔티티의 색상을 변경합니다:

```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" %}
**💡 팁**: 기존 `AssetLoad` 컴포넌트를 만든 후에, 예를 들어 플레이어 동작에 응답하여 더 많은 자산을 추가할 수 있습니다. 사용하려면 `AssetLoad.getOrCreateMutable()` 을 사용해 컴포넌트를 가져온 다음 새 경로를 `assets` 배열에 추가하세요. 등록된 콜백은 이렇게 새로 추가된 자산이 다운로드될 때도 실행됩니다.
{% endhint %}

{% hint style="info" %}
**💡 팁**: 이 컴포넌트의 작동 예시는 [`88,-12-asset-load`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/88,-12-asset-load) 테스트 씬으로, mp3, 텍스처, 비디오 및 glb를 하나의 `AssetLoad` 컴포넌트를 통해 사전 로드하고 `assetLoadLoadingStateSystem` 의도적으로 누락된 경로를 포함하여 `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-ko/sdk7/optimizing/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.