언리얼 엔진의 UFunctions | 언리얼 엔진 5.5 문서

UFunction 선언

UFunction 은 언리얼 엔진 리플렉션 시스템에 의해 인식되는 C++ 함수입니다. 모든 UObject 또는 블루프린트 함수 라이브러리는 UFUNCTION 매크로를 헤더 파일 내 함수 선언 윗줄에 배치하여 멤버 함수를 UFunction으로 선언할 수 있습니다. 이 매크로는 함수 지정자(Function Specifiers) 가 언리얼 엔진의 함수 해석 및 사용 방식을 변경하도록 지원합니다.

	UFUNCTION([specifier1=setting1, specifier2, ...], [meta(key1="value1", key2, ...)])
	ReturnType FunctionName([Parameter1, Parameter2, ..., ParameterN1=DefaultValueN1, ParameterN2=DefaultValueN2]) [const];

함수 지정자를 사용하면 UFunctions를 블루프린트 비주얼 스크립팅 그래프에 노출할 수 있으며, 이를 통해 개발자는 C++ 코드를 변경하지 않고도 블루프린트 에셋에서 UFunctions를 호출하거나 확장할 수 있습니다.

UFunctions는 클래스의 디폴트 프로퍼티에 있는 델리게이트에 바인딩 가능하여, 액션을 사용자 입력과 연결하는 등의 태스크를 수행할 수 있습니다. 또한 UFunctions는 네트워크 콜백 같은 역할을 할 수도 있는데, 이는 특정 변수가 네트워크 업데이트에 영향을 받을 때마다 UFunctions를 사용하여 알림을 수신하고 커스텀 코드를 실행할 수 있다는 것을 의미합니다.

또한 디버그, 환경설정 또는 치트 코드 명령이라고도 불리는 자신만의 콘솔 명령을 생성할 수도 있습니다. 이러한 콘솔 명령은 개발 빌드에서 게임 콘솔로부터 호출하거나, 레벨 에디터에서 게임 오브젝트에 커스텀 함수 기능이 있는 버튼을 추가할 수 있습니다.

함수 지정자

함수 선언시, Function Specifier (함수 지정자)를 선언에 붙여 함수가 엔진과 에디터의 다양한 부분과 어떻게 작동하는지를 제어할 수 있습니다.

함수 지정자	효과
`BlueprintAuthorityOnly`	네트워크 전권이 있는 머신(서버, 데디케이티드 서버, 싱글플레이어 게임)에서 이 함수를 실행하는 경우, 블루프린트 코드에서만 실행됩니다.
`BlueprintCallable`	이 함수는 블루프린트 또는 레벨 블루프린트 그래프에서 실행할 수 있습니다.
`BlueprintCosmetic`	이 함수는 장식성이라 데디케이티드 서버에서는 실행되지 않습니다.
`BlueprintGetter`	이 함수는 블루프린트 노출 프로퍼티에 대한 접근자로 사용됩니다. 이 지정자는 `BlueprintPure` 와 `BlueprintCallable` 을 내포합니다.
`BlueprintImplementableEvent`	이 함수는 블루프린트 또는 레벨 블루프린트 그래프에서 구현할 수 있습니다.
`BlueprintInternalUseOnly`	이 함수는 최종 사용자에게 노출시키지 말아야 함을 나타냅니다.
`BlueprintNativeEvent`	이 함수는 블루프린트 로 덮어쓰도록 디자인되었지만, 기본 내장 구현이 있기도 합니다. 메인 함수 이름 끝에 `_Implementation` 를 붙인 함수를 추가로 선언한 뒤 코드를 작성하면 됩니다. 자동생성 코드는 블루프린트 오버라이드를 찾지 못하면 "_Implementation" 메서드를 호출합니다.
`BlueprintPure`	이 함수는 어떤 식으로든 소유 오브젝트에 영향을 주지 않으며, 블루프린트 또는 레벨 블루프린트 그래프에서 실행할 수 있습니다.
`BlueprintSetter`	이 함수는 블루프린트 노출 프로퍼티의 뮤테이터로 사용됩니다. 이 지정자는 `BlueprintCallable` 을 내포합니다.
`CallInEditor`	이 함수는 디테일 패널의 버튼을 통해 선택된 인스턴스 상의 에디터에서 호출할 수 있습니다.
`Category = "TopCategory\\|SubCategory\\|Etc"`	이 함수를 블루프린트 편집 툴에 표시할 때의 카테고리를 지정합니다. 중첩 카테고리는 `\|` 연산자로 표시합니다.
`Client`	이 함수는 호출되는 오브젝트를 소유한 클라이언트에서만 실행됩니다. 메인 함수 이름 뒤에 `_Implementation` 를 붙인 함수를 추가로 선언합니다. 자동 생성 코드는 필요할 때 "_Implementation" 머소드를 호출합니다.
`CustomThunk`	UnrealHeaderTool 코드 생성기는 이 함수에 대해 썽크를 생산하지 않으며, 사용자가 제공해 줘야 합니다.
`Exec`	이 함수는 게임 내 콘솔에서 실행할 수 있습니다. 실행 명령은 특정 클래스 안에서 선언했을 때만 작동합니다.
`NetMulticast`	이 함수는 서버 로컬 및 모든 클라이언트에 리플리케이트되는 상황 양쪽에서, 액터의 `NetOwner` 와 상관 없이 실행됩니다.
`Reliable`	이 함수는 네트워크로 리플리케이트되며, 대역폭이나 네트워크 오류와 상관 없이 도착이 보장됩니다. `Client` 또는 `Server` 와 함께 사용했을 때만 유효합니다.
`SealedEvent`	이 함수는 서브클래스에서 덮어쓸 수 없습니다. `SealedEvent` 키워드는 이벤트에만 사용할 수 있습니다. 이벤트가 아닌 함수의 경우, `static` 또는 `final` 로 선언하면 봉인할 수 있습니다.
`ServiceRequest`	이 함수는 RPC (Remote Procedure Call) 서비스 요청입니다.
`ServiceResponse`	이 함수는 RPC 서비스 반응입니다.
`Server`	이 함수는 서버에서만 실행됩니다. 메인 함수 이름 뒤에 `_Implementation` 를 붙인 함수를 추가로 선언하고, 기거서 코드를 작성합니다. 자동생성 코드는 필요할 때 "_Implementation" 메서드를 호출합니다.
`Unreliable`	이 함수는 네트워크로 리플리케이트되지만 대역폭 제한이나 네트워크 오류로 인해 실패할 수 있습니다. `Client` 또는 `Server` 와 함께 사용했을 때만 유효합니다.
`WithValidation`	메인 함수 이름 뒤에 `_Validation` 를 붙인 함수를 추가로 선언합니다. 이 함수는 같은 파라미터를 받으며, 메인 함수 호출 진행 여부를 나타내는 `bool` 을 반환합니다.

메타데이터 지정자

클래스, 인터페이스, 구조체, 열거형, 열거형 값, 함수 또는 프로퍼티를 선언할 때 메타데이터 지정자 를 추가하여 엔진 및 에디터의 다양한 측면과 상호작용하는 방식을 제어할 수 있습니다. 각 데이터 구조 또는 멤버 타입에는 자체적인 메타데이터 지정자 목록이 있습니다.

메타데이터는 에디터에만 존재합니다. 메타데이터에 액세스하는 게임 로직을 작성하지 마세요.

함수 메타 태그	효과
`AdvancedDisplay="Parameter1, Parameter2, .."`	쉼표로 구분된 파라미터 목록을 고급 핀으로 표시합니다(UI 확장 필요).
`AdvancedDisplay=N`	`N` 을 숫자로 대체하고 N번째 이후의 모든 파라미터를 고급 핀으로 표시합니다(UI 확장 필요). 예를 들어 'AdvancedDisplay=2'는 처음 두 파라미터를 제외한 모든 파라미터를 고급으로 표시합니다.
`ArrayParm="Parameter1, Parameter2, .."`	`BlueprintCallable` 함수가 배열 함수 호출(Call Array Function) 노드를 사용해야 하고 나열된 파라미터가 와일드카드 배열 프로퍼티로 처리되어야 함을 나타냅니다.
`ArrayTypeDependentParams="Parameter"`	`ArrayParm` 을 사용하는 경우 이 지정자는 `ArrayParm` 목록에 있는 모든 파라미터의 타입을 결정하는 하나의 파라미터를 나타냅니다.
`AutoCreateRefTerm="Parameter1, Parameter2, .."`	나열된 파라미터는 레퍼런스로 전달되기는 하지만 핀이 연결 해제된 상태로 남아 있으면 자동으로 생성된 디폴트를 갖게 됩니다. 배열 핀에 자주 사용되는 블루프린트를 위한 편의 기능입니다.
`BlueprintAutocast`	블루프린트 함수 라이브러리의 스태틱 `BlueprintPure` 함수에서만 사용됩니다. 반환 타입과 함수의 첫 번째 파라미터 타입에 대해 형변환 노드가 자동으로 추가됩니다.
`BlueprintInternalUseOnly`	이 함수는 다른 함수나 노드를 구현하는 데 사용되는 내부 구현 디테일입니다. 블루프린트 그래프에 직접 노출되지 않습니다.
`BlueprintProtected`	이 함수는 블루프린트의 소유 오브젝트에서만 호출할 수 있습니다. 다른 인스턴스에서는 호출할 수 없습니다.
`CallableWithoutWorldContext`	클래스가 `GetWorld` 함수를 구현하지 않더라도 함수가 호출될 수 있음을 나타내기 위해 `WorldContext` 핀이 있는 `BlueprintCallable` 함수에 사용됩니다.
`CommutativeAssociativeBinaryOperator`	`BlueprintCallable` 함수가 가환 결합 이항(Commutative Associative Binary) 노드를 사용해야 함을 나타냅니다. 이 노드에는 핀 이름이 없지만 추가 입력 핀을 생성하는 핀 추가(Add Pin) 버튼이 있습니다.
`CompactNodeTitle="Name"`	`BlueprintCallable` 함수가 컴팩트 디스플레이 모드로 표시되어야 함을 나타내고, 해당 모드에서 표시할 이름을 제공합니다.
`CustomStructureParam="Parameter1, Parameter2, .."`	나열된 파라미터는 모두 와일드카드로 처리됩니다. 이 지정자는 사용자가 커스텀 `exec` 함수를 제공하도록 요구하는 `UFUNCTION` 레벨 지정자 `CustomThunk` 가 필요합니다. 이 함수에서는 파라미터 타입을 확인하고 해당 파라미터 타입을 기반으로 적절한 함수 호출을 수행할 수 있습니다. 베이스 `UFUNCTION` 은 호출되어서는 안 되며, 호출된 경우 어서트하거나 오류를 기록해야 합니다. 커스텀 `exec` 함수를 선언하려면 `DECLARE_FUNCTION(execMyFunctionName)` 구문을 사용합니다. 여기서 `MyFunctionName` 은 원래 함수의 이름입니다.
`DefaultToSelf`	`BlueprintCallable` 함수의 경우 오브젝트 프로퍼티의 명명된 기본값이 노드의 자체 컨텍스트여야 함을 나타냅니다.
`DeprecatedFunction`	이 함수에 대한 블루프린트 레퍼런스는 해당 함수가 지원 중단되었다는 컴파일 경고를 발생시킵니다. `DeprecationMessage` 메타데이터 지정자를 사용하여 지원 중단 경고 메시지에 추가할 수 있습니다(예: 지원 중단된 함수 교체에 대한 지침 제공).
`DeprecationMessage`="Message Text"	함수가 지원 중단된 경우 해당 함수를 사용하는 블루프린트를 컴파일하려고 할 때 표준 지원 중단 경고에 이 메시지가 추가됩니다.
`DeterminesOutputType="Parameter"`	함수의 반환 타입이 명명된 파라미터 핀에 연결된 입력과 일치하도록 동적으로 변경됩니다. 파라미터는 `TSubClassOf<X>` 또는 `TSoftObjectPtr<X>` 등의 템플릿 타입이어야 합니다. 여기서 함수의 원래 반환 유형은 `X` 또는 `TArray<X>` 와 같이 값 유형으로 `X*` 가 있는 컨테이너입니다.
`DevelopmentOnly`	`DevelopmentOnly` 로 표시된 함수가 개발(Development) 모드에서만 실행됩니다. 배포된 제품에는 없을 것으로 예상되는 디버그 출력과 같은 함수 기능에 유용합니다.
`DisplayName="Blueprint Node Name"`	블루프린트에서 이 노드의 이름이 코드 생성 이름 대신 여기에 제공된 값으로 대체됩니다.
`ExpandEnumAsExecs="Parameter"`	`BlueprintCallable` 함수의 경우 파라미터에서 사용하는 `enum` 의 각 항목에 대해 하나의 입력 실행 핀을 생성해야 함을 나타냅니다. 파라미터는 `UENUM` 태그가 있는 열거형 타입이어야 합니다.
`ForceAsFunction`	반환값이 없는 `BlueprintImplementableEvent` 를 이벤트에서 함수로 변경합니다.
`HidePin="Parameter"`	`BlueprintCallable` 함수의 경우 파라미터 핀이 사용자의 뷰에서 숨겨져야 함을 나타냅니다. 이 방식으로 함수당 하나의 핀만 숨길 수 있습니다.
`HideSelfPin`	함수가 호출되는 오브젝트를 나타내는 ‘self’ 핀을 숨깁니다. ‘self’ 핀은 호출하는 블루프린트 클래스와 호환되는 `BlueprintPure` 함수에서 자동으로 숨겨집니다. `HideSelfPin` 메타 태그를 사용하는 함수는 `DefaultToSelf` 지정자도 자주 사용합니다.
`InternalUseParam="Parameter"`	`HidePin`과 유사하게 사용자의 뷰에서 명명된 파라미터의 핀을 숨기고 함수당 하나의 파라미터에만 사용할 수 있습니다.
`KeyWords="Set Of Keywords"`	블루프린트 그래프에서 함수를 호출하기 위해 노드를 배치할 때처럼 이 함수를 검색할 때 사용할 수 있는 키워드 세트를 지정합니다.
`Latent`	레이턴트 액션을 나타냅니다. 레이턴트 액션에는 `FLatentActionInfo` 타입의 파라미터가 하나 있으며 이 파라미터의 이름은 `LatentInfo` 지정자를 통해 명명됩니다.
`LatentInfo="Parameter"`	레이턴트 `BlueprintCallable` 함수의 경우 어느 파라미터가 LatentInfo 파라미터인지 나타냅니다.
`MaterialParameterCollectionFunction`	`BlueprintCallable` 함수의 경우 머티리얼 오버라이드 노드를 사용해야 함을 나타냅니다.
`NativeBreakFunc`	`BlueprintCallable` 함수의 경우 함수가 표준 구조체 브레이크(Break Struct) 노드와 동일한 방식으로 표시되어야 함을 나타냅니다.
`NotBlueprintThreadSafe`	블루프린트 함수 라이브러리에만 유효합니다. 이 함수는 소유 클래스의 일반 `BlueprintThreadSafe` 메타데이터에 대한 예외로 처리됩니다.
`ShortToolTip="Short tooltip"`	부모 클래스 선택 툴 대화 상자와 같이 전체 툴팁이 지나칠 수 있는 일부 상황에서 사용되는 짧은 툴팁입니다.
`ToolTip="Hand-written tooltip`	코드 코멘트에서 자동으로 생성된 툴팁을 오버라이드합니다.
`UnsafeDuringActorConstruction`	이 함수는 액터 생성 중에 호출하는 것이 안전하지 않습니다.
`WorldContext="Parameter"`	`BlueprintCallable` 함수에서 연산이 발생하는 월드를 결정하는 파라미터를 나타내는 데 사용됩니다.
`ScriptName="DisplayName"`	이 클래스, 프로퍼티 또는 함수를 스크립팅 언어로 익스포트할 때 사용하는 이름입니다. 지원 중단된 이름을 세미콜론으로 구분된 추가 엔트리로 포함할 수 있습니다.

함수 파라미터 지정자

파라미터 지정자 설명

Out 파라미터가 레퍼런스에 의해 전달되는 것으로 선언하여, 함수에 의해 수정되도록 허용합니다.

Optional 호출자의 편의를 위해 선택적 키워드를 사용하여 특정 함수 파라미터를 옵션으로 만들 수 있습니다. 호출자가 지정하지 않는 선택적 파라미터 값은 함수에 따라 다릅니다. 예를 들어, SpawnActor 함수는 스폰되는 액터의 루트 컴포넌트의 위치 및 회전을 디폴트로 하는 선택적 위치 및 회전을 받습니다. 선택적 실행인자의 디폴트값은 = [value] 를 추가하여 지정할 수 있습니다. 예시는 다음과 같습니다. function myFunc(optional int x = -1) . 대부분의 경우 선택적 파라미터에 전달되는 값이 없을 때 변수 타입의 디폴트값 또는 제로(0, false, "", none)가 사용됩니다.

파라미터 지정자	설명
Out	파라미터가 레퍼런스에 의해 전달되는 것으로 선언하여, 함수에 의해 수정되도록 허용합니다.
Optional	호출자의 편의를 위해 선택적 키워드를 사용하여 특정 함수 파라미터를 옵션으로 만들 수 있습니다. 호출자가 지정하지 않는 선택적 파라미터 값은 함수에 따라 다릅니다. 예를 들어, `SpawnActor` 함수는 스폰되는 액터의 루트 컴포넌트의 위치 및 회전을 디폴트로 하는 선택적 위치 및 회전을 받습니다. 선택적 실행인자의 디폴트값은 `= [value]` 를 추가하여 지정할 수 있습니다. 예시는 다음과 같습니다. `function myFunc(optional int x = -1)` . 대부분의 경우 선택적 파라미터에 전달되는 값이 없을 때 변수 타입의 디폴트값 또는 제로(0, false, "", none)가 사용됩니다.

델리게이트

델리게이트(Delegates) 는 일반적이고, 타입이 안전한 방식으로 C++ 오브젝트에 관한 멤버 함수를 호출할 수 있습니다. 델리게이트는 임의 오브젝트의 멤버 함수에 동적으로 바인딩되어, 호출자가 오브젝트 타입을 모르더라도 미래의 어느 시점에 오브젝트에 관한 함수를 호출할 수 있습니다.

레퍼런스 및 사용 정보는 델리게이트 페이지를 참조하세요.

타이머

타이머(Timers) 는 액션이 딜레이 또는 일정 시간이 지난 후 수행되도록 예약합니다. 예를 들어, 플레이어가 파워업 아이템을 획득한 후 무적 상태가 되고, 10초가 지난 후 무적 상태가 되기 전으로 복원하고 싶을 수 있습니다. 아니면 플레이어가 유독 가스로 가득 찬 방에서 움직이는 동안 초당 1회씩 대미지를 적용하고 싶을 수도 있습니다. 타이머를 사용하여 이러한 액션을 구현할 수 있습니다.

레퍼런스 및 사용 정보는 게임플레이 타이머 페이지를 참조하세요.