UI Manager

Abstract

UI Manager 가 푸는 문제는 "창이 여러 개 겹쳤을 때 누가 맨 위이고, 아래 깔린 창은 어떻게 할 것인가"입니다. 폼을 그룹(층)으로 나누고, 그룹 안에서는 여는 순서대로 쌓으며, 위에 새 폼이 올라오면 아래 폼에게 "가려졌다"고 알려 줍니다. 이 페이지는 그 내부 규칙을, Unity 쪽 UI 시스템 페이지는 게임 코드에서의 사용법을 다룹니다.

폼이 받는 콜백 — 언제 무엇이 불리나

인벤토리 위에 확인 팝업이 뜨고 닫히는 상황으로 보면 이렇습니다.

사건	인벤토리 (아래)	확인 팝업 (위)
인벤토리를 연다	OnInit(처음 한 번) → OnOpen
팝업을 연다	OnCover — "가려졌다" (pauseCoveredUIForm 이 true 였다면 OnPause 도)	OnInit → OnOpen
매 프레임	OnUpdate — 일시정지됐다면 불리지 않는다	OnUpdate
팝업을 닫는다	OnReveal — "다시 드러났다" (일시정지였다면 OnResume)	OnClose → 풀로 → OnRecycle

OpenUIForm 의 네 번째 인자 pauseCoveredUIForm 이 "이 폼이 떠 있는 동안 아래 폼들을 멈출 것인가"입니다. 전체 화면을 덮는 창이면 true 로 줘서 아래 폼의 갱신을 아끼고, 반투명 팝업이면 false 로 둡니다.

ToyboxNightmare 에서 일어나는 일

HUDForm 과 PauseMenuForm 은 둘 다 Default 그룹에 있고, HUD 가 먼저 열립니다. 따라서 보통 일시정지 폼이 HUD 위에 쌓이고, HUD 는 게임 시작 직후부터 "Covered" 상태가 됩니다. (정확히는 "여는 순서"가 아니라 로드가 끝난 순서로 쌓입니다. 두 폼 모두 비동기로 로드되므로 순서가 중요한 폼은 그룹을 나누거나 앞 폼의 성공 이벤트를 받고 다음 폼을 엽니다.) pauseCoveredUIForm 을 주지 않았으므로(기본 false) HUD 의 OnUpdate 는 계속 돕니다.

여기서 눈여겨볼 설계가 하나 있습니다. 일시정지 메뉴는 ESC 를 누를 때 열리는 것이 아니라, 한 판 내내 열려 있고 안의 패널만 켜고 끕니다.

// PauseMenuForm
protected override void OnUpdate(float elapseSeconds, float realElapseSeconds)
{
    base.OnUpdate(elapseSeconds, realElapseSeconds);

    if (!IsCancelPressed()) return;

    Toggle();        // GamePause 전환 + 패널 SetActive
}

복사

ESC 입력을 폼 자신의 OnUpdate 에서 받으려면 폼이 살아 있어야 하기 때문입니다. "닫혀 있는 폼은 아무 콜백도 받지 못한다"는 규칙에서 나온 구조입니다. 다른 방법은 입력을 Procedure 나 별도 컴포넌트에서 받아 그때 OpenUIForm 하는 것이고, 폼이 무겁다면 그쪽이 낫습니다.

확장할 때 쓰게 되는 것들

•

userData 로 폼에 인자 넘기기. OpenUIForm("ConfirmForm", "Popup", new ConfirmParams("정말 나갈까요?", onYes)) → 폼의 OnOpen(object userData) 로 도착합니다. 같은 프리팹 하나로 내용이 다른 팝업을 띄우는 방법입니다.

•

중복 열기는 직접 막아야 합니다. 프레임워크는 같은 주소의 폼을 여러 번 여는 것을 막지 않습니다 — 두 번 부르면 두 개가 뜹니다. 알림 팝업처럼 여러 개가 떠야 하는 폼에는 그대로 쓰면 되고, 하나만 떠야 하는 폼은 HasUIForm(주소) / IsLoadingUIForm(주소) 로 먼저 확인합니다. 예제의 ProcedureMain.OpenOnce 가 그 일을 합니다.

•

RefocusUIForm. 이미 열려 있는 폼을 다시 맨 위로 올립니다. 탭 전환식 UI 에서 씁니다.

•

그룹 단위 일시정지. uiGroup.Pause = true 로 그룹 전체 폼을 한 번에 멈춥니다. 컷신 동안 게임 UI 를 얼리는 용도입니다.

이 에디션에서 다른 점 · 본문을 읽을 때 주의할 점

•

본문은 "Depth 값으로 렌더 순서 결정"이라고 하지만, 코어가 계산한 depth 는 헬퍼의 SetDepth 와 폼의 OnDepthChanged 로 전달될 뿐 실제 그리기 순서를 바꾸는 것은 Unity 쪽 구현의 몫입니다. 이 에디션의 기본 헬퍼는 그 구현이 비어 있어서, 예제는 폼 Canvas 의 Sorting Order 를 직접 지정했습니다(HUD 0, 일시정지 100). 폼이 많아지면 OnDepthChanged(uiGroupDepth, depthInUIGroup) 에서 Sorting Order 를 계산해 넣는 공통 베이스 클래스를 만드는 것이 정석입니다.

•

본문의 uiManager.AddUIGroup(...), uiManager.OpenUIForm(...) 은 코어 API 입니다. 게임 코드는 GameEntry.GetComponent<UIComponent>() 로 같은 이름의 메서드를 부르고, 그룹은 인스펙터에서 등록합니다.

•

OpenUIFormUpdate / OpenUIFormDependencyAsset 이벤트는 이 에디션에서 발생하지 않습니다.

•

폼 로직의 훅은 protected override 로 쓰고, UI 폼 프리팹 루트에는 UIFormLogic 스크립트를 반드시 붙여 둡니다.

UI 매니저 개요

UI Manager는 GameFramework의 핵심 시스템으로, 게임 애플리케이션에서 **UI 폼(화면, 창, 패널)**의 관리·로딩·표시 및 생명주기를 제어합니다.

이 시스템은 UI 요소를 계층 구조로 구성하고, 상태를 관리하며, UI 리소스를 효율적으로 재사용할 수 있는 포괄적인 솔루션을 제공합니다.

•

Entity 관리 → Entity Manager 참고

•

오디오 인터페이스 관리 → Sound Manager 참고

아키텍처 개요

1. UIManager

UIManager 클래스는 모든 UI 작업을 총괄하는 메인 컨트롤러입니다.

기능:

•

UI 그룹 컬렉션 유지

•

UI 폼 열기·닫기 처리

•

객체 풀(Object Pool)로 UI 폼 인스턴스 관리

•

리소스 매니저를 통해 UI 폼 에셋 로드

•

UI 폼 생명주기 이벤트 제공

2. UI 그룹

UI 그룹은 동일한 깊이(Depth) 설정을 공유하는 UI 폼 컨테이너입니다.

이를 통해 UI를 논리적 레이어(배경, 게임 UI, 팝업창 등)로 구성 가능.

특징:

•

고유 이름과 Depth 값 보유

•

우선순위 기반 UI 폼 리스트

•

표시/가림/일시정지 제어

•

그룹 내 UI 폼의 쌓이는 순서 관리

3. UI 폼

UI 폼은 개별 UI 인터페이스 요소입니다. 상태는 다음과 같습니다:

•

Active: 표시되고 상호작용 가능

•

Covered: 표시되지만 위에 다른 폼이 있음

•

Paused: 일시 비활성 (대개 다른 폼에 가려질 때)

•

Hidden: 표시되지 않음

UI 폼 생명주기

Loading – 리소스에서 UI 폼 에셋 로드

Initializing – 인스턴스화 및 초기화

Opening – 표시되며 Active 상태로 전환

Cover/Reveal – 다른 폼이 위에 나타나거나 사라짐

Pause/Resume – 일시 비활성/재활성

Closing – 표시에서 제거 중

Recycling – 객체 풀로 반환

UI 그룹 관리

UI 그룹 사용 장점:

•

레이어 제어 – Depth 값으로 렌더 순서 결정

•

일괄 작업 – 그룹 단위로 일시정지/재개 가능

•

독립 스택 관리 – 각 그룹은 자체 UI 폼 스택 유지

UI 폼 열기·닫기 과정

열기

요청한 UI 폼이 이미 로드 중인지 확인

객체 풀에서 UI 폼 인스턴스 검색

없으면 Resource Manager를 통해 로드

로드 완료 시 인스턴스화 → 해당 그룹에 추가

초기화 및 열기 콜백 호출

UI 그룹 새로고침(상태 업데이트)

닫기

해당 UI 폼을 그룹에서 제거

닫기 콜백 호출

그룹 새로고침

객체 풀로 반환

CloseUIFormComplete 이벤트 발생

객체 풀 및 리소스 관리

•

객체 풀: UI 폼 인스턴스 재사용

•

리소스 매니저 연동 (원작 기준. 이 에디션의 Addressables 구현은 우선순위·진행률·종속 에셋 통지를 전달하지 않는다):

◦

우선순위 기반 로드

◦

진행률 보고

◦

종속 에셋 로드

◦

로드 중인 폼 닫기 (로드가 끝나면 바로 버린다)

이벤트 시스템

UI Manager는 다음 이벤트를 제공:

•

OpenUIFormSuccess – 성공적으로 열렸을 때

•

OpenUIFormFailure – 열기 실패 시

•

OpenUIFormUpdate – 로딩 진행률 보고

•

OpenUIFormDependencyAsset – 종속 에셋 로드 시

•

CloseUIFormComplete – 완전히 닫혔을 때

UI 폼 상태 관리

상태 변화 시:

•

상태 업데이트

•

해당 상태 콜백 호출 (OnCover, OnPause 등)

•

Depth 값 재조정

•

PauseCoveredUIForm 여부에 따라 가려진 폼 일시정지 여부 결정

•

UIGroup.Refresh()가 스택 위치 기반으로 상태 갱신

프레임워크 통합

UI Manager는 GameFramework 전반과 동일한 패턴 사용:

•

GameFrameworkModule 상속

•

ObjectPoolManager·ResourceManager 의존성 주입

•

플랫폼별 구현을 위한 Helper 인터페이스 사용

•

표준 이벤트 시스템 활용

•

객체 풀 기반 효율적 리소스 관리

사용 예시

UI 그룹 추가

uiManager.AddUIGroup("MainMenuGroup", 10, uiGroupHelper);
uiManager.AddUIGroup("PopupGroup", 20, uiGroupHelper);

복사

UI 폼 열기

int serialId = uiManager.OpenUIForm("MainMenu", "MainMenuGroup");

// 우선순위 + 가려진 폼 일시정지
int serialId = uiManager.OpenUIForm("SettingsPanel", "PopupGroup", 100, true, userData);

복사

UI 폼 닫기

uiManager.CloseUIForm(serialId);
uiManager.CloseUIForm(uiForm);

복사

포커스 재설정

uiManager.RefocusUIForm(uiForm);

복사

요약

UI Manager는 그룹 기반 아키텍처, 객체 풀, 상태 관리를 결합해 복잡한 UI를 효율적으로 처리하는 강력한 시스템입니다.

Resource Manager와 결합해 유연성을 유지하면서도 일관된 API로 UI를 제어할 수 있습니다.