Resource Management System

Abstract

리소스 시스템은 "이름을 주면 에셋을 비동기로 가져다 주는" 창구입니다. 엔티티·UI·사운드·씬 모듈이 전부 이 창구를 통해 에셋을 얻습니다. 그래서 게임 코드가 직접 부를 일은 거의 없습니다 — ShowEntity("Girl", …) 을 부르면 그 안에서 리소스 시스템이 돕니다. 이 에디션에서 그 창구 뒤에 있는 것은 Unity 의 Addressables 입니다.

실무에서 필요한 순간

•

새 프리팹·사운드·UI 를 게임에 추가할 때 — 등록 방법과 주소 규칙을 알아야 한다

•

엔티티나 UI 가 아닌 에셋(ScriptableObject, 텍스처, 텍스트)을 코드로 불러와야 할 때

•

"아무것도 안 뜬다"를 디버깅할 때

ToyboxNightmare 에서는

ResourceComponent 를 직접 부르는 코드가 한 줄도 없습니다. 에셋 25개가 전부 ShowEntity / OpenUIForm / PlaySound 를 통해 로드됩니다.

확장하려면

•

원격 배포·패치 → Resource Updating(리소스 업데이트)-Addressable

•

내부 구조, 다른 로더로 교체 → Resource Management(리소스 관리)-Addressable

로딩 경로

graph LR
    A["ShowEntity / OpenUIForm / PlaySound"] --> B["코어 매니저<br>(EntityManager 등)"]
    B --> C["IResourceManager"]
    C --> D["ResourceManager"]
    D --> E["Addressables.LoadAssetAsync"]

Mermaid

복사

게임 코드는 맨 왼쪽만 씁니다. 나머지는 프레임워크가 연결해 둔 배관입니다.

기억할 규칙은 하나 — 에셋 이름 = Addressables 주소

호출	넘기는 문자열	Addressables 에 등록된 것
ShowEntity(id, typeof(Enemy), "Zombunny", "Enemy", data)	"Zombunny"	Zombunny.prefab 의 주소 Zombunny
OpenUIForm("HUDForm", "Default")	"HUDForm"	HUDForm.prefab 의 주소 HUDForm
PlaySound("PlayerHurt", "Soundeffects", position)	"PlayerHurt"	Player Hurt.wav 의 주소 PlayerHurt
SceneComponent.LoadScene("Assets/Scenes/Stage01.unity")	전체 경로	씬의 주소 (씬만은 Assets/ 로 시작하고 .unity 로 끝나야 한다)

주소가 한 글자라도 다르면(대소문자 포함) 로드가 실패합니다. 실패는 예외가 아니라 실패 이벤트로만 오고, 화면에는 아무 일도 일어나지 않습니다.

주소 문자열을 코드 곳곳에 직접 적지 말고 상수 클래스에 모으세요. 예제는 UITable, SoundTable, EnemyTable 에 모아 두었습니다.

새 에셋을 게임에 추가하는 절차

Window → Asset Management → Addressables → Groups 를 연다.

에셋을 그룹으로 끌어다 놓는다.

주소를 짧은 키로 바꾼다. (여러 개 선택 → 우클릭 → Simplify Addressable Names)

상수 클래스에 그 문자열을 추가하고, 코드에서 ShowEntity / OpenUIForm / PlaySound 에 넘긴다.

엔티티 프리팹이라면 로직 스크립트를 붙이지 않은 상태로, UI 폼 프리팹이라면 루트에 UIFormLogic 을 붙인 상태로 등록합니다.

직접 에셋을 로드해야 할 때

엔티티·UI·사운드가 아닌 에셋은 ResourceComponent 를 직접 씁니다.

ResourceComponent resource = GameEntry.GetComponent<ResourceComponent>();

resource.LoadAsset("EnemyStats", new LoadAssetCallbacks(
    (assetName, asset, duration, userData) => { mStats = (EnemyStatsAsset)asset; },
    (assetName, status, errorMessage, userData) => { Log.Error("로드 실패: {0}", errorMessage); }));

// 다 썼으면 반드시 돌려준다. 로드 1회당 정확히 1회
resource.UnloadAsset(mStats);

복사

규칙	이유
결과는 콜백에서 받는다	로드는 비동기다. 호출 다음 줄에서는 아직 없다
LoadAsset 한 번에 UnloadAsset 한 번	짝이 안 맞으면 에셋이 메모리에서 내려가지 않는다
실패 콜백을 비워 두지 않는다	주소 오타를 찾을 유일한 단서다

ResourceComponent 의 API

메서드	용도
LoadAsset(주소, callbacks[, userData])	에셋 하나를 비동기로 로드
UnloadAsset(asset)	로드한 에셋을 돌려준다
LoadScene / UnloadScene	씬 로드·언로드. 보통 SceneComponent 를 통해 쓴다
UnloadUnusedAssets(performGCCollect)	아무도 참조하지 않는 에셋 정리를 예약한다. 스테이지 전환 직후에 부른다
ForceUnloadUnusedAssets(performGCCollect)	간격 제한 없이 다음 프레임에 정리한다

LoadAsset 에는 타입(assetType)과 우선순위(priority)를 받는 오버로드도 있지만, 이 에디션에서는 둘 다 무시되고 주소만으로 로드합니다.

원작 GameFramework 문서를 함께 볼 때

원작의 문서나 예제(StarForce 등)에는 이 에디션에 없는 기능이 나옵니다. 헷갈리지 않도록 정리합니다.

원작에 나오는 것	이 에디션
에셋 이름에 전체 경로 ("Assets/GameMain/Entities/Player.prefab")	Addressables 주소 ("Player")
리소스 모드, 버전 확인, 리소스 업데이트 Procedure	없음. 패치는 Addressables API 로 직접 한다
Resource Editor / Builder / Analyzer 창	없음. Addressables Groups 창을 쓴다
LoadBinary	미지원. TextAsset 으로 등록해 LoadAsset 으로 읽는다
HasAsset 으로 존재 확인	항상 "있음"을 돌려주므로 확인 용도로 쓸 수 없다
로딩 진행률·의존 에셋 이벤트	발생하지 않는다. 성공·실패 이벤트만 온다

실행 전에 확인할 것

Addressables Groups 창의 Play Mode Script 를 Use Asset Database (fastest) 로 두세요. 이 값은 Library/ 에 저장되어 git 으로 공유되지 않으므로, 프로젝트를 받은 사람마다 한 번씩 해야 합니다. Use Existing Build 인 채로 번들을 빌드한 적이 없으면 모든 로드가 실패해 엔티티가 하나도 뜨지 않습니다(01. 프로젝트 세팅 — 프레임워크가 켜지는 최소 조건).