UE Angel Script Override

AngelScript에서 Override 네 가지

구분	문법	의미
Unreal 이벤트 구현	UFUNCTION(BlueprintOverride)	C++/Unreal Blueprint Event에 AngelScript 구현 연결
Script 메서드 재정의	void Function() override	AngelScript 부모 메서드 재정의
Blueprint 확장 지점	UFUNCTION(BlueprintEvent)	Blueprint 자식이 AngelScript 함수를 재정의하도록 허용
C++ 함수 호출	UFUNCTION(BlueprintCallable) 또는 UFUNCTION(ScriptCallable)	C++ 함수를 Script에서 호출하도록 바인딩

BlueprintCallable은 호출용 지정자이며 Override를 의미하지 않는다. 일반 C++ virtual 함수는 Unreal Reflection 이벤트가 아니므로 BlueprintOverride로 재정의할 수 없다.

C++ virtual 재정의는 C++ 컴파일러와 vtable의 기능이고, BlueprintOverride는 Unreal Reflection과 Blueprint Event 호출 경로를 사용한다. AngelScript의 일반 메서드 override는 Script 클래스 상속 규칙을 사용한다.

C++ 이벤트

BlueprintOverride : Unreal의 Blueprint Event 및 Reflection 호출 경로에 AngelScript 구현을 연결한다.

대표적인 대상은 BeginPlay, Tick, ConstructionScript와 같은 부모 Unreal 클래스 이벤트다. 함수 이름과 매개변수는 부모 API 또는 IDE의 Override 자동완성으로 확인한다.

C++ 이벤트 이름은 AngelScript 바인딩 과정에서 일부 접두어가 제거될 수 있다. Receive, BP_, K2_, Received_가 대표적인 단순화 대상이다.

프로젝트 C++ 함수를 AngelScript Override 대상으로 만들기 위한 조건:

• C++ 클래스가 UCLASS()로 Unreal에 등록되어야 한다.
• 함수가 UFUNCTION(BlueprintImplementableEvent) 또는 UFUNCTION(BlueprintNativeEvent)여야 한다.
• AngelScript 함수의 이름과 매개변수가 부모 이벤트와 일치해야 한다.
• C++ 선언이 헤더에 있어야 한다.
• C++ 빌드와 Unreal Header Tool 처리가 완료되어 Reflection 정보가 갱신되어야 한다.

C++ 이벤트 지정자:
| 지정자 | 동작 |
| --- | --- |
| BlueprintImplementableEvent | C++ 기본 구현 없이 Blueprint 또는 AngelScript가 구현 |
| BlueprintNativeEvent | C++ 기본 구현을 유지하면서 Blueprint 또는 AngelScript가 재정의 |
| BlueprintCallable | 외부에서 호출 가능하지만 Override 대상은 아님 |
| ScriptCallable | Blueprint에는 노출하지 않고 AngelScript에서 호출. 포크 지원 여부 확인 필요 |

• Super 제한 : C++ BlueprintNativeEvent 기본 구현은 AngelScript에서 직접 호출할 수 없음.
• 우회 방식 : C++ 기본 동작을 ResetCharacterBase()와 같은 별도 호출 함수로 분리한 뒤 AngelScript Override에서 호출.

C++ 연동

목적	C++ 선언	AngelScript 동작
C++ 함수 호출	UFUNCTION(BlueprintCallable)	Script에서 함수 호출
Script 전용 C++ 함수 호출	UFUNCTION(ScriptCallable)	Blueprint에는 숨기고 Script에서 호출
자식 구현 지점 제공	UFUNCTION(BlueprintImplementableEvent)	Script에서 BlueprintOverride로 구현
C++ 기본 구현 + 자식 재정의	UFUNCTION(BlueprintNativeEvent)	Script에서 BlueprintOverride로 구현

C++ 전용 선언이 없는 Script 메서드는 C++에서 직접 호출할 수 없다. C++에서 Script 구현을 호출하려면 UFUNCTION() 또는 Blueprint Event를 통해 Unreal Reflection 호출 경로를 사용해야 한다.

C++ 일반 virtual 함수와 AngelScript 일반 메서드는 서로 자동으로 연결되지 않는다. C++에서 AngelScript Override를 호출해야 하는 함수는 Reflection 기반 이벤트로 설계한다.

C++ 클래스와 멤버를 Script에 노출하는 기준:

• 클래스는 UCLASS() 기반 Unreal 타입이어야 한다.
• 함수는 UFUNCTION(BlueprintCallable), UFUNCTION(BlueprintPure) 또는 포크가 지원하는 UFUNCTION(ScriptCallable)이어야 한다.
• 프로퍼티는 바인딩 가능한 UPROPERTY 접근 지정자를 사용해야 한다.
• NotInAngelscript 메타데이터가 있거나 Deprecated된 함수는 바인딩되지 않을 수 있다.
• C++ 헤더 변경 후에는 C++ 빌드와 Editor의 Reflection 갱신이 필요하다.

예를 들어 Widget에서 소유 PlayerController를 가져와 C++ 클래스로 변환하는 형태는 Cast<ACXPlayerController>(GetOwningPlayer())다. 이후 함수 호출 가능 여부는 Cast가 아니라 해당 C++ 함수의 AngelScript 바인딩 여부로 결정된다.

Script 상속과 Super

AngelScript 부모 클래스의 일반 메서드는 void Function() override 형태로 재정의한다. 일반 Script 메서드는 별도로 BlueprintEvent를 선언하지 않아도 Script 자식에서 재정의할 수 있다.

Super::Function() 호출 규칙:

• AngelScript 부모의 일반 메서드: Super::Function() 호출 가능.
• AngelScript 부모의 BlueprintEvent: BlueprintOverride로 구현하고 Super::Function() 호출 가능.
• C++ 부모의 BlueprintNativeEvent: C++ 기본 구현을 호출하는 Super 사용에 제한이 있음.

부모 메서드를 재정의했을 때 부모 로직까지 실행해야 한다면 Script 부모 메서드에는 Super::Function()을 호출한다. BeginPlay와 Tick 같은 Unreal 이벤트는 이벤트별 지원 규칙에 따라 부모 호출 여부를 결정한다.

override와 BlueprintOverride의 차이:

문법	대상	호출 경로
override	AngelScript 메서드	Script 메서드 dispatch
BlueprintOverride	Unreal Blueprint Event	Unreal Reflection/Event dispatch

Blueprint 확장

BlueprintEvent : AngelScript 함수를 Blueprint 자식이 재정의할 수 있게 하는 지정자다. 기본 구현을 비워두면 구현 없는 이벤트처럼 사용할 수 있다.

핵심 로직과 확장 이벤트는 분리한다. 반드시 실행되어야 하는 처리는 일반 Script 메서드에 두고, Blueprint가 선택적으로 추가 동작을 넣을 지점만 BlueprintEvent로 제공한다. 이렇게 하면 Blueprint 자식이 부모 호출을 누락해도 핵심 로직이 사라지지 않는다.

Delegate와 Override는 다른 기능이다.

기능	의미
Override	부모의 한 구현을 자식 구현으로 교체하거나 확장
Delegate/Event Dispatcher	이벤트 발생 시 등록된 함수를 호출

Delegate에 연결하는 AngelScript 함수는 UFUNCTION()이어야 한다. 동적 Delegate와 Event Dispatcher는 Unreal Reflection에 노출된 함수만 대상으로 한다.

제한과 설계

IInterface/UInterface : 현재 AngelScript에서 공식 지원되지 않는다.

공개 커뮤니티에서 사용하는 우회 방식은 다음과 같다.

• 공통 AActor 기반 클래스를 만든다.
• 공통 클래스에 BlueprintNativeEvent 또는 BlueprintImplementableEvent를 선언한다.
• AngelScript 클래스가 인터페이스 대신 공통 Actor를 상속한다.

이 방식은 진짜 Unreal Interface 다형성과 다르며 공통 기반 Actor라는 설계 비용이 생긴다.

Editor 전용 API는 패키징된 게임에서 사용할 수 없다. Actor Label, Editor Subsystem, Editor Visualizer 같은 기능을 Script에서 사용할 때는 #if EDITOR 조건으로 제한한다.

BlueprintOverride의 호출 비용은 C++ 직접 호출과 동일하지 않다. 정확한 비용은 함수 내용, 호출 빈도, 바인딩 방식, 최적화, 빌드 설정에 따라 달라진다. 고빈도 반복, 물리, 경로 계산, 대량 데이터 처리는 C++ API로 분리하고 Script에는 게임 규칙과 상태 조합을 둔다.

AngelScript는 패키징 시 Script를 미리 컴파일하거나 생성된 C++ 코드를 포함해 VM 실행을 네이티브 코드로 대체하는 Precompiled Script 경로를 제공한다. 이 기능은 실행 속도 개선에 사용할 수 있지만 C++ 재빌드와 별도 배포 과정이 필요하다.

권장 역할 분담:

• C++: UObject/Actor/Component 기반 클래스, 저장 데이터, 네트워크 구조, 플랫폼 코드, 고성능 계산, Script에 노출할 API.
• AngelScript: 입력, 상태 전환, 전투, 퀘스트, 상호작용, UI 연결, Blueprint Event 구현.
• Blueprint: UMG 시각 구성, Animation Blueprint, Material, Niagara, Control Rig 등 에셋 중심 작업.

자료

• Functions and BlueprintEvents
• Automatic Bindings
• Differences with Unreal C++
• Properties and Accessors
• Delegates and Events
• Editor-Only Script
• Development Status
• Using Precompiled Scripts
• Reddit: What's the current state of AngelScript?
• Reddit: AngelScript is an absolute game changer
• Epic Developer Community: Simple Code Editor for Blueprint Scripting