Unreal Engine Singleton

구분	생성 주체	생명주기	UObject 기반	월드/PIE 대응	주 용도
Game Singleton	Engine 설정	Engine 생명주기	가능	약함	전역 데이터 객체
Subsystem	Unreal Framework	종류별로 다름	가능	강함	시스템 단위 기능
GameInstance	Unreal Framework	게임 실행 세션	가능	강함	레벨 전환 후 유지 데이터

---

Game Singleton

Unreal Editor의 Project Settings에서 지정하는 Game Singleton은 UEngine이 관리하는 전역 UObject 인스턴스다.
Project Settings 또는 DefaultEngine.ini에서 Singleton 클래스를 지정할 수 있다.

[/Script/Engine.Engine]
GameSingletonClassName=/Script/MyGame.MyGameSingleton

접근은 GEngine->GameSingleton을 통해 한다.

UMyGameSingleton* Singleton = Cast<UMyGameSingleton>(GEngine->GameSingleton);

if (Singleton)
{
    // 전역 데이터 접근
}

특징

항목	설명
생성 위치	Engine 초기화 과정
소유자	UEngine
생명주기	엔진이 살아있는 동안 유지
레벨 전환	유지됨
PIE	여러 PIE 환경에서 의도치 않게 공유될 수 있음
네트워크	서버/클라이언트 개념과 직접 연결되지 않음

---

Subsystem

Subsystem은 Unreal이 제공하는 공식적인 시스템 확장 구조다.
직접 Singleton을 만들지 않고도 특정 생명주기에 맞는 전역성 객체를 만들 수 있다.

대표적인 Subsystem 종류는 다음과 같다.

Subsystem	Outer	생명주기	사용 예
UEngineSubsystem	Engine	엔진 전체	엔진 단위 서비스
UGameInstanceSubsystem	GameInstance	게임 실행 세션	인벤토리, 세이브, 매치 데이터
UWorldSubsystem	World	월드 단위	스폰 관리, 월드 이벤트 관리
ULocalPlayerSubsystem	LocalPlayer	로컬 플레이어 단위	입력, UI, 플레이어 설정
UEditorSubsystem	Editor	에디터 실행 중	에디터 툴, 자동화 기능

기본 구조

UCLASS()
class UMyGameSubsystem : public UGameInstanceSubsystem
{
    GENERATED_BODY()

public:
    virtual void Initialize(FSubsystemCollectionBase& Collection) override;
    virtual void Deinitialize() override;
};

void UMyGameSubsystem::Initialize(FSubsystemCollectionBase& Collection)
{
    Super::Initialize(Collection);

    // 초기화
}

void UMyGameSubsystem::Deinitialize()
{
    // 정리

    Super::Deinitialize();
}

접근

UMyGameSubsystem* Subsystem = GetGameInstance()->GetSubsystem<UMyGameSubsystem>();

if (Subsystem)
{
    // 시스템 기능 사용
}

또는 World Context가 있을 경우:

UGameInstance* GI = UGameplayStatics::GetGameInstance(GetWorld());
UMyGameSubsystem* Subsystem = GI->GetSubsystem<UMyGameSubsystem>();

특징

항목	설명
생성 주체	Unreal Framework
초기화 함수	Initialize()
종료 함수	Deinitialize()
UObject 기반	가능
GC 관리	안전
Blueprint 노출	가능
PIE 대응	GameInstance, World, LocalPlayer 기준으로 분리 가능

---

GameInstance

UGameInstance는 게임 실행 세션 동안 유지되는 객체다.
레벨이 바뀌어도 파괴되지 않는다.

UCLASS()
class UMyGameInstance : public UGameInstance
{
    GENERATED_BODY()

public:
    UPROPERTY()
    int32 Gold;

    UPROPERTY()
    FString PlayerName;
};

접근은 다음과 같다.

UMyGameInstance* GI = Cast<UMyGameInstance>(UGameplayStatics::GetGameInstance(GetWorld()));

if (GI)
{
    GI->Gold += 100;
}

특징

항목	설명
생성 주체	Unreal Framework
생명주기	게임 시작부터 종료까지
레벨 전환	유지됨
월드 종속성	특정 World에 직접 종속되지는 않음
PIE 대응	PIE 인스턴스마다 별도 GameInstance 생성
멀티플레이	서버와 클라이언트가 각각 자기 GameInstance를 가짐
Replication	직접 복제되지 않음

GameInstance는 데이터를 들고 있는 게임 세션 객체이다.
기능이 많아지면 GameInstance가 비대해지기 쉬우므로, 시스템별 기능은 UGameInstanceSubsystem으로 분리하는 편이 좋다.

---

생명주기 비교

flowchart TD
    A[Engine 시작] --> B[Game Singleton 생성]
    A --> C[EngineSubsystem 생성]

    B --> D[게임 실행]
    C --> D

    D --> E[GameInstance 생성]
    E --> F[GameInstanceSubsystem 생성]

    F --> G[World 생성]
    G --> H[WorldSubsystem 생성]

    H --> I[Level 이동]
    I --> G

    E --> J[게임 종료]
    J --> K[GameInstance / Subsystem 정리]
    K --> L[Engine 종료]
    L --> M[Game Singleton 정리]

객체	레벨 전환 시 유지	게임 종료 시 제거	엔진 종료까지 유지
Game Singleton	유지	경우에 따라 유지	유지
GameInstance	유지	제거	제거
GameInstanceSubsystem	유지	제거	제거
WorldSubsystem	제거 후 새 월드에서 재생성	제거	제거

---

Game Singleton vs GameInstance

구분	Game Singleton	GameInstance
소유자	UEngine	게임 실행 세션
설정 위치	Project Settings / ini	Project Settings의 GameInstance Class
생성 시점	엔진 초기화 쪽	게임 실행 시작
레벨 전환	유지	유지
PIE 분리	상대적으로 약함	PIE 인스턴스별 분리
Runtime 상태 관리	부적합	가능
플레이어 세션 데이터	부적합	적합

게임 중 변하는 데이터라면 Game Singleton보다 GameInstance 또는 GameInstanceSubsystem이 더 적합하다.

---

GameInstance vs GameInstanceSubsystem

구분	GameInstance	GameInstanceSubsystem
역할	게임 세션의 중심 객체	세션 단위 기능 모듈
구조	하나의 클래스에 기능이 모이기 쉬움	기능별 분리 가능
확장성	낮아질 수 있음	높음
초기화	Init()	Initialize()
종료	Shutdown()	Deinitialize()
접근	GetGameInstance()	GetSubsystem<T>()
추천 용도	세션 핵심 데이터	인벤토리, 세이브, 매치, 로딩 등 시스템

---

사용 기준

목적	추천 구조
레벨 이동 후 유지되는 플레이어 데이터	GameInstance
GameInstance에 붙는 시스템 기능	UGameInstanceSubsystem
월드마다 따로 존재해야 하는 시스템	UWorldSubsystem
로컬 플레이어별 UI / 입력 / 설정	ULocalPlayerSubsystem
엔진 전체에서 하나만 필요한 기능	UEngineSubsystem
에디터 툴 기능	UEditorSubsystem
읽기 전용 전역 데이터 접근	Game Singleton 또는 DataAsset
순수 C++ 유틸리티	직접 Singleton 또는 static 함수
게임 중 변하는 전역 상태	Subsystem 권장
Actor 참조 관리	WorldSubsystem 또는 Manager Actor
멀티플레이 상태	GameState, PlayerState, replicated Actor