> 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의 목록에서 에셋을 제거해도 `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(
      `Asset ${assetLoadState.asset} is now: ${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 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-ko/sdk7/optimizing/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.