리소스 미리 불러오기

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

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

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

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

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: 자산의 상태를 알 수 없습니다.

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

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

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

💡 팁: 이 컴포넌트의 작동 예시는 88,-12-asset-load 테스트 씬으로, mp3, 텍스처, 비디오 및 glb를 하나의 AssetLoad 컴포넌트를 통해 사전 로드하고 assetLoadLoadingStateSystem 의도적으로 누락된 경로를 포함하여 NOT_FOUND.