내일배움캠프 45일차 TIL 2026/06/25

📝 [TIL] 언리얼 엔진 C++ UI 제어 및 게임 프레임워크 확장

1. 100% C++ 기반의 UI 제어 (meta = (BindWidget))

블루프린트의 이벤트 그래프나 바인딩 노드를 단 한 개도 쓰지 않고, 순수 C++ 코드로 위젯 내부의 컴포넌트들을 직접 제어하는 방법을 배웠다.

• 핵심 메커니즘: UPROPERTY(meta = (BindWidget))을 사용했다. C++ 변수명과 위젯 에디터(WBP)에 배치한 컴포넌트의 이름을 정확히 일치시키면 엔진이 자동으로 둘을 메모리상에서 묶어준다(포인터 매핑).
• UI 부모 클래스 교체: 위젯 에디터의 파일(File) -> 클래스 세팅(Class Settings)에서 부모 클래스를 기본 UserWidget 대신 직접 만든 C++ 커스텀 위젯 클래스로 교체해야 C++ 로직이 정상 작동함을 확인했다.
• NativeTick 활용: NativeTick을 오버라이드하여 매 프레임 전광판 데이터를 감시하고 UI 텍스트(SetText)를 실시간으로 업데이트했다.

2. 레벨 전환 시 데이터 보존 (GameInstance 싱글톤 패턴)

기존 GameState에 데이터를 저장하면 OpenLevel로 맵이 전환될 때 데이터가 통째로 날아가는 문제를 해결하기 위해 영구 저장소를 구축했다.

• GameState vs GameInstance:
  • GameState: 현재 맵(레벨)의 전광판이다. 맵이 바뀌면 파괴된다(휘발성).
  • GameInstance: 게임 프로그램 그 자체다. EXE가 종료될 때까지 메모리에 딱 하나만 유지되며 절대 죽지 않는다(영속성).
• 프로젝트 전역 관리자: 프로젝트 세팅(Game Instance Class)에 직접 만든 클래스를 등록하면 엔진이 알아서 게임 시작 시 싱글톤(단 하나만 존재)으로 생성한다.
• 접근 방식: 헤더에 변수를 따로 만들지 않아도, 전역 헬퍼 함수인 GetWorld()->GetGameInstance()를 호출하고 내 클래스로 Cast(형변환)만 거치면 언제 어디서든 영구 금고(TotalScore)에 접근할 수 있다.

3. 메인 메뉴 구현과 게임모드(GameMode) 분리 아키텍처

인게임과 메인 메뉴는 규칙(캐릭터 생성 여부, 조작법 등)이 완전히 다르므로 게임모드를 분리하는 정석 구조를 설계했다.

• 역할 분담:
  • SpartaMainMenuGameMode (연출가): 맵이 켜질 때 마우스 커서를 강제로 켜고(bShowMouseCursor = true), 입력 모드를 UI 전용(FInputModeUIOnly)으로 묶은 뒤, 메인 메뉴 위젯을 화면에 찍어내는 환경을 조성했다.
  • SpartaMainMenuWidget (실무자): 화면에 뜬 시작/종료 버튼의 클릭 이벤트(OnClicked.AddDynamic)를 받아 실제 레벨을 열거나(OpenLevel) 게임을 종료(QuitGame)하는 행동을 처리했다.
• 월드 세팅(World Settings): 언리얼은 레벨(맵)마다 게임모드를 다르게 오버라이드할 수 있다. 메인 메뉴 레벨의 월드 세팅에만 전용 게임모드를 지정하여 인게임 규칙과 완벽히 격리했다.

4. 레벨 전환 시 입력 모드(Input Mode)의 오염과 해결

• 문제점: 메인 메뉴에서 입력 모드를 UIOnly로 잠그고 마우스 커서를 켜둔 상태에서 OpenLevel을 하니, 다음 맵(Level1)으로 넘어가도 그 세팅이 그대로 유지되어 캐릭터가 먹통이 되는 현상이 발생했다.
• 해결책: 인게임 레벨이 시작되는 시점(SpartaGameState::BeginPlay)에 플레이어 컨트롤러를 가져와 마우스 커서를 다시 끄고(bShowMouseCursor = false), 입력 모드를 게임 전용(FInputModeGameOnly)으로 리셋해 줌으로써 조작 권한을 캐릭터에게 안전하게 돌려주었다.