Unreal Engine C++ Core Dictionary · Vol. 2
언리얼 엔진 C++ Core API 포스트잇 백과 2탄
1탄이 UObject, 리플렉션, 컨테이너의 기본기를 다뤘다면 2탄은 소프트 참조, 비동기 에셋 로딩, Asset Manager, Timer, Subsystem, Interface, Actor 생성 흐름으로 이어집니다. UE 5.4부터 UE 5.8까지 실무 코드에서 계속 반복되는 C++ Core 패턴을 20개 카드로 나누어 정리했습니다.
TSoftObjectPtr
적용 엔진: UE 5.4 ~ 5.8 · 지연 로딩과 약한 에셋 참조 패턴 유지
핵심 요약TSoftObjectPtr<T>는 UObject를 직접 붙잡지 않고 에셋 경로를 통해 참조합니다. 필요할 때 로드할 수 있어 하드 레퍼런스를 줄이고 초기 메모리 부담을 낮추는 데 유용합니다.
Q. 일반 UObject 포인터와 가장 큰 차이는?
A. 일반 포인터는 이미 메모리에 있는 객체를 가리키는 성격이 강하고, TSoftObjectPtr는 디스크상의 경로를 보관해 필요 시 로드하는 흐름에 적합합니다.
TSoftClassPtr
적용 엔진: UE 5.4 ~ 5.8 · 클래스 에셋의 소프트 참조에 사용
핵심 요약TSoftClassPtr<T>는 블루프린트 클래스나 클래스 에셋을 경로 기반으로 참조합니다. 스폰할 후보 클래스는 필요하지만 바로 로드하고 싶지 않을 때 자주 사용합니다.
Q. TSubclassOf와 어떻게 다른가요?
A. TSubclassOf는 로드된 클래스 타입 제한에 가깝고, TSoftClassPtr는 아직 로드되지 않은 클래스 에셋을 경로로 들고 있을 수 있습니다.
FSoftObjectPath
적용 엔진: UE 5.4 ~ 5.8 · 문자열 기반 에셋 경로 표현
핵심 요약FSoftObjectPath는 패키지, 최상위 에셋, 서브오브젝트 경로를 담는 구조체입니다. 소프트 참조, 쿠킹, 리다이렉트 처리와 연결되는 기반 타입입니다.
Q. 경로 문자열만 들고 있으면 위험하지 않나요?
A. 언리얼의 소프트 경로 타입은 에디터, 쿠킹, 리다이렉트 흐름과 함께 동작하도록 설계되어 단순 문자열보다 안전하게 에셋 참조를 표현합니다.
FTopLevelAssetPath
적용 엔진: UE 5.4 ~ 5.8 · 최상위 에셋 식별 경로 타입
핵심 요약FTopLevelAssetPath는 패키지와 에셋명을 분리된 FName 형태로 보관해 최상위 에셋을 표현합니다. 소프트 경로 내부 표현을 이해할 때 함께 알아두면 좋습니다.
Q. 왜 경로를 통째 문자열로만 저장하지 않나요?
A. 이름 테이블, 비교, 메모리 사용 측면에서 엔진 친화적인 표현이 필요하기 때문입니다. 경로가 많아질수록 표현 방식 차이가 의미를 가집니다.
FStreamableManager
적용 엔진: UE 5.4 ~ 5.8 · 동기/비동기 에셋 스트리밍 관리
핵심 요약FStreamableManager는 소프트 경로로 지정된 에셋을 동기 또는 비동기로 로드하는 데 사용됩니다. 로딩 핸들을 통해 완료 시점과 수명 관리를 함께 다룹니다.
Q. 왜 모든 에셋을 시작할 때 로드하지 않나요?
A. 초기 로딩 시간과 메모리 사용량이 커집니다. 필요한 순간에 로드하면 큰 프로젝트에서 시작 비용과 런타임 메모리 압박을 줄일 수 있습니다.
Asynchronous Asset Loading
적용 엔진: UE 5.4 ~ 5.8 · 소프트 참조 기반 비동기 로딩 흐름
핵심 요약비동기 에셋 로딩은 게임 흐름을 멈추지 않고 필요한 에셋을 준비하는 방식입니다. UI, 장비, 적 캐릭터, 월드 조각처럼 상황에 따라 필요한 리소스에 특히 중요합니다.
Q. 비동기 로딩 후 바로 포인터를 써도 되나요?
A. 로딩 완료 콜백이나 핸들 상태를 확인한 뒤 접근해야 합니다. 완료 전에는 소프트 참조가 아직 유효 객체로 해석되지 않을 수 있습니다.
UAssetManager
적용 엔진: UE 5.4 ~ 5.8 · Primary Asset 중심 에셋 관리
핵심 요약UAssetManager는 Primary Asset ID, 번들, 로딩 정책을 통해 프로젝트 에셋을 체계적으로 관리합니다. 규모가 커질수록 단순 참조보다 관리형 로딩이 중요해집니다.
Q. Asset Manager를 쓰면 무엇이 좋아지나요?
A. 에셋을 식별자와 번들 단위로 묶어 로딩 정책을 통제할 수 있습니다. DLC, 대형 인벤토리, 캐릭터 스킨 같은 구조에서 장점이 큽니다.
하드 참조와 소프트 참조
적용 엔진: UE 5.4 ~ 5.8 · 레퍼런스 의존성 관리의 기본 구분
핵심 요약하드 참조는 대상 에셋을 함께 로드하게 만들 수 있고, 소프트 참조는 경로만 보관해 필요할 때 로드합니다. 로딩 시간, 메모리, 패키징 의존성에 직접적인 영향을 줍니다.
Q. 모든 참조를 소프트로 바꾸면 좋은가요?
A. 아닙니다. 항상 필요한 핵심 에셋은 하드 참조가 단순하고 안전합니다. 선택적이거나 큰 리소스일수록 소프트 참조가 유리합니다.
Asset Picker 메타데이터
적용 엔진: UE 5.4 ~ 5.8 · AllowedClasses, MetaClass 등 사용
핵심 요약소프트 경로나 클래스 선택 프로퍼티에는 메타데이터를 붙여 에디터 선택 범위를 제한할 수 있습니다. 잘못된 에셋 선택을 UI 단계에서 줄이는 실무 방어선입니다.
Q. C++ 타입만 맞으면 에디터 선택도 자동으로 완벽한가요?
A. 항상 그렇지는 않습니다. 프로퍼티 메타데이터로 선택 가능한 클래스나 카테고리를 좁히면 디자이너 작업 실수를 크게 줄일 수 있습니다.
FTimerManager
적용 엔진: UE 5.4 ~ 5.8 · 지연 호출과 반복 실행 관리
핵심 요약FTimerManager는 일정 시간 뒤 함수나 델리게이트를 호출하고, 반복 타이머를 관리합니다. FTimerHandle로 일시정지, 재개, 취소, 남은 시간 조회를 처리합니다.
Q. Tick 대신 Timer를 쓰면 좋은 경우는?
A. 매 프레임 필요 없는 주기적 작업에는 Timer가 더 명확합니다. 쿨다운, 지연 실행, 일정 주기 검사 같은 로직에 적합합니다.
SetTimerForNextTick
적용 엔진: UE 5.4 ~ 5.8 · 다음 틱으로 호출을 넘기는 패턴
핵심 요약SetTimerForNextTick은 현재 호출 흐름을 바로 이어가지 않고 다음 틱에 함수를 실행하게 합니다. 초기화 순서가 꼬일 수 있는 상황에서 한 프레임 뒤로 미루는 데 쓰입니다.
Q. 그냥 바로 함수 호출하면 안 되나요?
A. 컴포넌트 등록, 월드 초기화, 다른 객체 BeginPlay 순서가 아직 끝나지 않은 경우가 있습니다. 다음 틱으로 넘기면 의존 객체가 준비될 시간을 줄 수 있습니다.
Actor Tick
적용 엔진: UE 5.4 ~ 5.8 · 프레임 업데이트와 Tick 비용 관리
핵심 요약Tick은 매 프레임 실행되는 업데이트 경로입니다. PrimaryActorTick.bCanEverTick, Tick Interval, Tick Group을 조절해 불필요한 프레임 비용을 줄여야 합니다.
Q. 모든 Actor에 Tick을 켜도 되나요?
A. 피하는 것이 좋습니다. 이벤트, Timer, 상태 변화 기반 로직으로 대체할 수 있으면 Tick을 끄는 편이 성능 관리에 유리합니다.
UGameInstance
적용 엔진: UE 5.4 ~ 5.8 · 게임 실행 인스턴스 전체 수명 관리
핵심 요약UGameInstance는 게임 실행 동안 유지되는 상위 관리 객체입니다. 맵 전환을 넘어 유지해야 하는 세션, 로그인, 전역 상태의 출발점으로 자주 사용됩니다.
Q. GameMode와 GameInstance의 차이는?
A. GameMode는 월드/레벨 규칙에 가깝고 맵마다 바뀔 수 있습니다. GameInstance는 게임 실행 단위로 더 오래 살아남습니다.
USubsystem
적용 엔진: UE 5.4 ~ 5.8 · 관리 수명을 가진 확장 시스템
핵심 요약Subsystem은 Engine, Editor, GameInstance, World, LocalPlayer 같은 엔진 구성 요소의 수명에 맞춰 자동 생성되는 확장 지점입니다. 싱글턴 남발을 줄이는 좋은 선택지입니다.
Q. Subsystem을 쓰는 이유는?
A. 수명과 접근 경로가 엔진에 의해 관리되므로 전역 매니저를 직접 만들 때보다 초기화와 해제가 정돈됩니다.
UGameInstanceSubsystem
적용 엔진: UE 5.4 ~ 5.8 · GameInstance 수명 공유
핵심 요약UGameInstanceSubsystem은 GameInstance와 같은 수명으로 자동 생성되는 시스템입니다. 계정, 세션, 전역 데이터 캐시처럼 맵 전환을 넘어 유지되는 기능에 적합합니다.
Q. GameInstance에 모든 기능을 직접 넣으면 안 되나요?
A. 가능하지만 커질수록 책임이 섞입니다. Subsystem으로 나누면 기능별 초기화, 테스트, 유지보수가 쉬워집니다.
UWorldSubsystem
적용 엔진: UE 5.4 ~ 5.8 · World 단위 시스템에 사용
핵심 요약UWorldSubsystem은 특정 World의 수명과 함께 생성되고 사라지는 시스템입니다. 월드별 스폰 관리, 환경 상태, 레벨 단위 서비스에 어울립니다.
Q. GameInstanceSubsystem과 어떻게 고르나요?
A. 맵 전환 후에도 유지되어야 하면 GameInstance 쪽, 특정 World에 종속되어야 하면 World 쪽이 자연스럽습니다.
UINTERFACE와 IInterface
적용 엔진: UE 5.4 ~ 5.8 · 리플렉션 가능한 인터페이스 패턴
핵심 요약언리얼 인터페이스는 리플렉션용 UINTERFACE 클래스와 실제 함수 계약을 담는 IInterface 계층으로 나뉩니다. 서로 다른 Actor를 같은 방식으로 호출할 때 유용합니다.
Q. 왜 클래스가 두 개처럼 보이나요?
A. UINTERFACE는 리플렉션 노출을 위한 껍데기이고, 실제 C++ 함수 계약은 I... 인터페이스 쪽에 들어갑니다.
TScriptInterface
적용 엔진: UE 5.4 ~ 5.8 · UObject 인터페이스 참조 보관
핵심 요약TScriptInterface<T>는 UObject와 인터페이스 포인터를 함께 다루는 타입입니다. 블루프린트와 C++ 양쪽에서 인터페이스 구현 객체를 변수로 보관할 때 등장합니다.
Q. 그냥 인터페이스 포인터만 저장하면 안 되나요?
A. 언리얼 리플렉션과 UObject 수명 체계에서는 UObject 정보가 함께 필요합니다. TScriptInterface는 그 연결을 표현합니다.
UWorld::SpawnActor
적용 엔진: UE 5.4 ~ 5.8 · 런타임 Actor 생성의 기본 API
핵심 요약SpawnActor는 Actor 파생 클래스를 월드에 생성합니다. 클래스, 위치, 회전, Transform, FActorSpawnParameters를 통해 생성 조건을 제어합니다.
Q. UObject 생성과 Actor 생성 API가 다른 이유는?
A. Actor는 World에 배치되고 레벨, 네트워크, 충돌, 트랜스폼 흐름에 참여합니다. 그래서 NewObject가 아니라 UWorld::SpawnActor를 사용합니다.
FActorSpawnParameters
적용 엔진: UE 5.4 ~ 5.8 · Actor 생성 옵션 묶음
핵심 요약FActorSpawnParameters는 Owner, Instigator, 이름, 충돌 처리, 생성 플래그 등 Actor 스폰 조건을 전달하는 구조체입니다. 스폰 결과가 달라질 수 있어 옵션 의미를 알아두어야 합니다.
Q. SpawnActor가 실패할 수 있는 대표 이유는?
A. 잘못된 클래스, 월드 포인터 문제, 충돌 처리 정책, 추상 클래스, 권한 문제 등이 원인이 될 수 있습니다. 반환값 null 체크는 기본입니다.