Resource Building Pipeline

Abstract

"어떤 에셋을 어느 묶음에 넣고, 어떻게 빌드해서 내보내는가"가 빌드 파이프라인의 일입니다. 이 에디션에서 그 답은 전부 Addressables Groups 창에 있습니다. 프레임워크는 런타임 코드만 대신하고, 에셋을 등록하고 묶고 빌드하는 일은 이 창에서 직접 합니다.

실무에서 필요한 순간

•

새 에셋을 추가했는데 게임에서 로드되지 않을 때

•

에디터에서는 되는데 빌드한 게임에서 에셋이 안 뜰 때

•

앱 용량이나 로딩 시간을 줄이려고 묶음을 나눌 때

ToyboxNightmare 에서는

Prefabs 그룹 하나에 25개가 들어 있고, 한 번들로 묶입니다(Pack Together) — 캐릭터 2(Girl, Boy), 적 5(Zombunny, ZomBear, Hellephant, Clown, ZombieDuck), 아군 2(Sheep, Dog), 투사체·피격 이펙트 5, UI 폼 2(HUDForm, PauseMenuForm), 사운드 클립 8, 배경 Environment. 전부 앱 안에 들어가는 Local 그룹입니다.

Groups 창

Window → Asset Management → Addressables → Groups

위치	하는 일
그룹 목록	에셋을 끌어다 놓아 등록하고, 주소를 고친다
Play Mode Script	에디터에서 플레이할 때 에셋을 어디서 읽을지 고른다
Build	번들을 빌드한다 (New Build, Update a Previous Build, Clear Build Cache)
Tools	설정·프로필·라벨·분석 창을 연다

에셋 등록

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

주소를 짧은 키로 바꾼다. 기본값은 전체 경로(Assets/Art/Prefabs/Zombunny.prefab)다. 여러 개를 선택해 우클릭 → Simplify Addressable Names 를 누르면 파일 이름만 남는다.

코드에서 그 문자열 그대로 ShowEntity / OpenUIForm / PlaySound 에 넘긴다.

등록은 반드시 Groups 창에서 합니다. 그룹 에셋 파일을 텍스트로 직접 고치면 GUID 가 어긋나 조용히 로드에 실패합니다. 또 씬은 주소를 줄이지 않고 전체 경로(Assets/….unity)를 그대로 둡니다 — 프레임워크의 SceneComponent 가 그 형식을 요구합니다.

Play Mode Script — 에디터에서 어디서 읽을까

모드	읽는 곳	쓰는 때
Use Asset Database (fastest)	프로젝트의 에셋을 직접. 번들 빌드가 필요 없다	개발 중 기본값
Use Existing Build	미리 빌드해 둔 번들	출시 전 검증, 원격 로드·패치 시험

이 설정은 Library/ 에 저장되어 git 으로 공유되지 않습니다. 프로젝트를 새로 받으면 한 번 확인해야 하고, Use Existing Build 인데 번들을 빌드한 적이 없으면 엔티티가 하나도 뜨지 않습니다.

그룹을 어떻게 나눌까

그룹은 번들의 단위이자 배포의 단위입니다. 작은 게임은 그룹 하나로 충분하고, 커지면 아래 기준으로 나눕니다.

기준	나누는 방법	얻는 것
같이 쓰이는가	스테이지별, 화면별로 그룹을 나눈다	안 쓰는 스테이지의 에셋이 메모리에 올라오지 않는다
자주 바뀌는가	밸런스 데이터·이벤트 UI 를 따로 둔다	패치 때 작은 번들만 다시 받는다
앱에 넣을 것인가	Local 그룹 / Remote 그룹	설치 용량을 줄이고 나머지를 첫 실행 때 받는다

그룹 설정의 Bundle Mode 로 그룹 안에서도 묶는 방식을 고릅니다.

Bundle Mode	결과	맞는 경우
Pack Together	그룹 전체가 번들 하나	항상 같이 쓰이는 에셋 (예제가 이 방식)
Pack Separately	에셋마다 번들 하나	따로따로 쓰이는 큰 에셋 (스테이지 씬, 배경음)
Pack Together By Label	같은 라벨끼리 번들 하나	그룹을 늘리지 않고 묶음을 조절하고 싶을 때

번들 하나에서 에셋 하나만 필요해도 번들 전체가 메모리에 올라옵니다. 그리고 그 번들의 에셋을 하나라도 쓰는 동안에는 번들이 내려가지 않습니다. "같이 쓰이는 것끼리 묶는다"가 기본 원칙인 이유입니다.

빌드

메뉴	하는 일
Build → New Build → Default Build Script	모든 그룹의 번들과 카탈로그를 새로 만든다
Build → Update a Previous Build	이전 빌드와 비교해 바뀐 것만 다시 만든다 (패치용)
Build → Clear Build Cache → All	빌드 캐시를 비운다. 빌드 결과가 이상할 때

플레이어(게임 실행 파일)를 빌드할 때 Addressables 번들을 함께 빌드할지는 Addressables Settings 의 Build Addressables on Player Build 로 정합니다. 기본값은 Unity 환경설정을 따르며, 환경설정의 기본은 "함께 빌드"입니다. CI 처럼 단계를 나누고 싶을 때 끕니다.

분석 도구

Groups 창의 Tools → Window 아래에 있습니다.

도구	알려 주는 것
Analyze	여러 번들에 중복으로 들어간 에셋. 예를 들어 두 그룹의 프리팹이 같은 머티리얼을 쓰는데 그 머티리얼을 등록하지 않았다면 양쪽 번들에 복사본이 하나씩 들어간다. 찾아서 공용 그룹으로 빼 준다
Addressables Report	마지막 빌드의 번들별 크기와 내용물, 의존 관계
Labels	라벨 관리. "미리 받을 묶음"처럼 여러 에셋을 한꺼번에 가리킬 때 쓴다
Profiles	빌드 경로·로드 경로(개발 서버 / 운영 CDN) 전환

실행 중의 핸들·번들 상태는 Unity Profiler 의 Addressables 모듈에서 봅니다.

출시 전 점검

코드의 주소 상수가 모두 Groups 창에 등록돼 있다 (오타는 컴파일 에러가 아니라 실패 이벤트로만 드러난다)

Play Mode Script 를 Use Existing Build 로 바꾸고 번들을 빌드해 한 판을 끝까지 플레이해 봤다

Analyze 로 중복 에셋을 확인했다

엔티티 프리팹에 로직 스크립트가 붙어 있지 않고, UI 폼 프리팹에는 붙어 있다

확인이 끝난 뒤 Play Mode Script 를 Use Asset Database 로 되돌렸다

"에디터에서는 되는데 빌드에서 안 된다"의 흔한 원인은 에디터가 번들을 거치지 않고 에셋을 읽기 때문입니다. Use Asset Database 모드에서는 에셋을 고치면 바로 반영되지만, 빌드된 게임은 마지막으로 빌드한 번들을 씁니다. 번들이 오래됐거나, 번들로 묶는 과정에서만 드러나는 문제(빠진 의존 에셋, 제거된 셰이더 변형)가 있으면 에디터에서는 보이지 않습니다. 그래서 출시 전에 Use Existing Build 로 한 번 돌려 보는 단계가 필요합니다.

원격 배포와 패치는 Resource Updating(리소스 업데이트)-Addressable 에서 이어집니다.