Unreal Engine/개념정리

[UE5] - UGameplayStatics

KimGeon-U 2025. 2. 5. 23:51

Controller에서 레벨을 열거나, UParticleSystemComponent를 사용한 파티클 생성, 월드에 배치되어있는 액터를 검색하기 등등 다양한 경우에서 인스턴스화 하지않은 UGameplayStatics를 사용하게 되었습니다.

게임 프로젝트를 제작하며 계속되서 사용되는 정적으로 사용되는 해당 클래스가 어떠한 기능을 하는지 알아보게되었으며,

학습한 자료들을 이번 포스팅에 작성하겠습니다.

 

UGameplayStatics

  • 게임 플레이 관련 유틸리티 함수를 제공하는 정적(Static) 클래스
    • 유틸리티 기능을 빠르게 호출하며, 대부분 전역적인 게임 월드에 의존한다.
    • 따라서 매번 객체를 만들지 않고 정적 클래스 및 함수로 설계되어 빠르게 호출 할 수 있다.
  • 인스턴스를 생성하지 않고 직접 호출한다.
    • UGameplayStatics::FunctionName()
  • 오디오, 내비게이션, 액터 생성,파괴, 게임 레벨 관리, 데미지/충돌 처리, 세이브/로드 등 게임 제작에 필요한 시스템들을 쉽게 사용할 수 있도록 도와준다.
    • 공통 기능들을 쉽게 호출할 수 있도록 설계된 유틸리티 클래스
  • 엔진의 다양한 시스템과 통합되어있어 AI, UI, Physcis등과 연계가 가능하다.
  • 빠르고 간편하게 사용할 수 있으며, 객체 생성이 불필요하여 메모리 관리 시 용이하다.
    • 동적 환경에서 객체를 만들고 삭제하는 메모리 생성값을 줄여 오버헤드를 줄일 수 있다.
  • 남용하거나 잘못된 사용시 성능적으로 문제가 발생 할 수 있다.
    • Ex) GetAllActorsOfClass : 월드에 배치된 모든 액터들을 검색한다.

 

UGameplayStatics::Function(...)

오디오 / 사운드

  • PlaySoundAtLocation
    • 특정 위치에서 사운드 재생
  • PlaySound2D
    • 2D 사운드 재생
  • SpawnSoundAtLocation
    • 게임 내 특정 위치에 사운드 생성, 재생

 

위치 / 내비게이션

  • GetPlayerPawn
    • 특정 플레이어의 Pawn 반환한다.
  • GetPlayerCharacter
    • 특정 플레이어의 Character 반환한다.
  • GetAllActorsOfClass
    • 특정 클래스의 모든 액터를 반환한다.
  • GetActorOfClass
    • 특정 클래스의 첫번째 액터 반환
  • ProjectPointToNavigation
    • 특정 지점을 내비게이션 메시상의 유효한 위치로 변환한다.

 

액터 생성/ 파괴

  • SpawnActor
    • 게임 월드에 새로운 액터 동적으로 생성
    • GetWorld()->SpawnActor와 동일하다.
    • GetWorld()->SpawnActorDeferred  = BeginDeferredActorSpawnFromClass 
  • DestroyActor
    • 특정 액터 삭제

 

게임 흐름 및 레벨 관리

  • OpenLevel
    • 특정 레벨을 불러온다.
  • GetCurrentLevelName
    • 현재 레벨의 이름을 반환한다.
  • SetGamePaused
    • 게임을 일시정지 / 해제한다
  • SetGlobalTimeDilation
    • 게임의 전체적인 시간의 흐름을 조정한다.

 

데미지 및 충돌처리

  • ApplyDamage
    • 액터에 피해를 가한다.
  • ApplyRadialDamage
    • 특정 반경 내에 있는 모든 액터에 피해를 가한다.
  • ApplyPointDamage
    • 특정 지점에서 한개의 액터에게만 피해를 가한다.

 

카메라 및 뷰 관련 기능

  • GetPlayerCameraManager
    • 특정 플레이어의 CameraManager 반환
  • SetGlobalTimeDilation
    • 전체 게임 속도를 조정하여 슬로우 모션 또는 빠른 진행 효과 연출

 

세이브 / 로드

  • CreateSaveGameObject
    • 세이브 데이터 객체 생성
  • SaveGameSlot
    • 데이터를 특정 슬룻에 저장
  • LoadGameFromSlot
    • 특정 슬룻에서 저장된 데이터를 불러온다.