Scene System Architecture

1. 목적

Scene은 단순한 Unreal Map이 아니라, 게임에서 독립적으로 진입하고 종료되는 논리 단위다.

Scene = Map + 진입 초기화 + 종료 정리 + UI + 입력 상태 + 리소스

현재 게임의 Map 단위 Scene은 TitleMap, LobbyMap, 6개의 개별 Challenge Map이다. 일시정지 화면은 Map이 아니라 현재 Scene 위에 여는 UI다. 클리어 뒤에는 별도 결과 화면 없이 Lobby로 이동한다.

2. 구성

UKzSceneSubsystem
    ├─ CurrentScene
    ├─ ChangeScene
    └─ Transition / Loading / Input Lock

UKzScene
    ├─ UKzSceneDefinition 참조
    ├─ Initialize
    └─ Release

UKzSceneDefinition
    ├─ TargetMap
    ├─ SceneClass
    ├─ PreloadAssets
    ├─ DefaultWidgets
    └─ InputMode

UKzSceneSubsystem은 레벨 전환 후에도 유지되어야 하므로 UGameInstanceSubsystem을 기반으로 한다.

UKzScene은 특정 Scene의 진입과 종료 규칙을 구현하는 프로젝트 객체다. Unreal의 ULevel 또는 UWorld 자체를 의미하지 않는다.

UKzSceneDefinition은 에디터에서 설정하는 UPrimaryDataAsset이다. Scene마다 필요한 Map, 리소스, 기본 UI, 입력 상태를 한 곳에 정의한다.

정식 실행의 최초 Map은 TitleMap이다. TitleMap의 시작 요청은 LobbyMap SceneDefinition을 선택해 ChangeScene을 호출한다. 테스트 진입점은 이 정식 흐름과 분리한다.

3. 책임

UKzSceneSubsystem

• Scene 전환 중복 방지
• CurrentScene 관리
• 전환 페이드, 로딩 UI, 입력 잠금 처리
• 현재 Scene의 Release와 다음 Scene의 Initialize 호출
• Map Travel 또는 Streaming Level 로드·언로드 요청
• 전환 완료 또는 실패 시 입력과 전환 UI 상태 복구

GameInstance 진행 상태

GameInstance는 Scene 전환을 직접 결정하지 않고, 전환 뒤에도 남아야 하는 진행 데이터만 보관한다. UKzGameInstance는 UKzSaveGame을 통해 이 데이터를 저장·로드한다.

• 클리어한 Challenge ID 목록

Challenge 내부의 퍼즐, 물리 오브젝트, 적 상태는 GameInstance에 보관하지 않는다. 재시작은 현재 Challenge Map을 다시 로드하고, Lobby 복귀는 완료 목록만 유지한다.

현재 범위에서는 GameFlowManager, ProgressManager, ChallengeManager를 별도로 두지 않는다. Title UI, Lobby 입구, Challenge 클리어 트리거, 재시작 메뉴가 기존 SceneSubsystem에 직접 전환을 요청한다.

UKzScene

• SceneDefinition에 정의된 리소스 준비
• 기본 UI 열기
• Scene 전용 입력 상태 적용
• Scene 전용 게임 시스템 시작
• 종료 시 열었던 UI 닫기
• Scene 전용 입력 상태 해제
• Scene 전용 리소스 참조 해제 및 시스템 정리

UKzSceneDefinition

• TargetMap: 진입 대상 Map
• SceneClass: 생성할 UKzScene 클래스
• PreloadAssets: 진입 전에 준비할 리소스 목록
• DefaultWidgets: 진입 후 열 기본 UI 목록
• InputMode: Scene에서 사용할 입력 상태

UKzSceneTransitionComponent

맵에 배치하는 입구·클리어 액터에 붙이는 재사용 컴포넌트다. Transition() 호출 시 NextSceneDefinition으로 이동한다. CompletedChallengeId가 설정돼 있으면 이동 전에 UKzGameInstance에 완료 기록을 저장한다.

• Lobby의 챌린지 입구: 대상 Challenge SceneDefinition만 설정한다.
• Challenge의 클리어 트리거: Lobby SceneDefinition과 완료 Challenge ID를 설정한다.

4. 전환 종류

ChangeScene

현재 Scene을 완전히 교체한다.

Fade Out
    → CurrentScene.Release
    → 현재 Map 정리
    → TargetMap Travel
    → NextScene.Initialize
    → Fade In

정식 전환 흐름은 다음과 같다.

TitleMap --시작--> LobbyMap --도전 선택--> Challenge Map
Challenge Map --재시작--> 같은 Challenge Map
Challenge Map --클리어/복귀--> LobbyMap

현재 범위에서는 별도 결과 화면을 열지 않고, 클리어 기록 뒤 즉시 Lobby Scene으로 전환한다. 결과 화면은 필요성이 확인될 때 Challenge Scene 위의 UI로 추가한다.

5. 입력과 UI 규칙

Scene은 UI를 직접 생성·보관하지 않는다. UI 생성과 재활용은 UKzUISubsystem이 담당한다.

UKzScene.Initialize
    → UKzUISubsystem.Open(DefaultWidget)

UKzScene.Release
    → UKzUISubsystem.Close(Scene이 연 Widget)

전환 중 입력 잠금은 UKzSceneSubsystem이 관리한다. Scene이 활성화된 뒤의 일반 입력 모드는 SceneDefinition의 InputMode를 기준으로 적용한다.

6. 리소스 규칙

Scene별 리소스는 PreloadAssets에 TSoftObjectPtr 또는 Primary Asset으로 등록한다.

Scene Initialize
    → 필요한 리소스 비동기 로드
    → 로딩 진행률 반영
    → Scene Setup

Scene Release
    → Scene 전용 시스템 정리
    → 리소스 핸들 참조 해제

리소스의 실제 해제 시점은 Unreal GC와 Asset Manager가 결정한다. Scene은 자신이 잡은 스트림 핸들만 해제한다.

7. Unreal Map과의 관계

UKzScene
    = 게임 논리 단위

UWorld / ULevel
    = Unreal 런타임 Map 단위

ChangeScene은 Map Travel을 사용한다. 컷씬은 Level Sequence / Sequencer에서 처리하며, Scene 전환과 별도 기능으로 둔다.

Map Travel 중에는 기존 UWorld가 제거되므로, 전환 상태를 유지하는 UKzSceneSubsystem은 UGameInstanceSubsystem이어야 한다.

8. 구현 순서

1. UKzSceneDefinition 데이터 에셋 정의
2. UKzScene 베이스 클래스 정의
3. UKzSceneSubsystem의 ChangeScene 전환 구현
4. Fade, Loading UI, 입력 잠금 연결
5. Scene별 리소스 비동기 로드 연결

9. 현재 구현 상태

구현됨:

• UKzSceneSubsystem의 기본 ChangeScene
• UKzGameInstance와 UKzSaveGame의 Challenge 완료 목록 저장·로드
• Lobby 입구·Challenge 클리어 트리거용 UKzSceneTransitionComponent

연결 필요:

• UI에서 호출할 현재 Scene 재시작 API
• Title 시작 버튼, Lobby 입구, Challenge 클리어 트리거의 실제 Blueprint 연결
• Scene 전환 전후 UI·입력 정리
• Title, Lobby, 각 Challenge SceneDefinition 데이터 에셋 설정