虚幻引擎版本: Unreal Engine 5.6
编辑器: Rider For Unreal
在阅读本文之前希望你对虚幻引擎以及蓝图有基本的了解

0. 引言

当我们打开几乎任意一个虚幻项目的C++代码（如下），都可以看到一些很“奇怪”的宏，诸如：UCLASS、GENERATED_BODY、UPROPERTY以及UFUNCTION。它们当中一些还可以携带参数，这些宏在虚幻（UE C++）中到底起了什么作用呢？这篇文章会带大家了解这些宏背后的内容，以及它们的常见用法。这是我们开启UE C++ 旅程的必备知识。

UCLASS(Abstract, Blueprintable)
class PARROT_API AParrotPlayerCharacter : public AParrotCharacterBase
{
	GENERATED_BODY()
public:

	// When true, the player wants to jump
	UFUNCTION(BlueprintCallable, BlueprintPure, Category = "Parrot|Input")
	bool IsJumpInputActive() const { return bPressedJump; }
	virtual void CheckJumpInput(float DeltaTime) override; 
	virtual bool CanJumpInternal_Implementation() const override;

	UFUNCTION(BlueprintCallable)
	bool IsEnemyJumpValid(UBoxComponent* HurtBox); 

	// Executes a jump from an enemy's hurt box
	void JumpFromEnemyHurtBox(); 
public:
	UPROPERTY(BlueprintAssignable)
	FOnHitpointsAdded OnHitpointsAdded; 
protected:
	UPROPERTY(BlueprintReadWrite, EditDefaultsOnly, meta = (ClampMin = "0.0", UIMin = "0.0", Category = "Parrot|Character|Stats"))
	float HitStunDuration = 0.0f; 

	// When true, allows the player to be stunned in mid-air 
	UPROPERTY(BlueprintReadWrite, EditDefaultsOnly, meta = (EditConditionHides, EditCondition = "HitStunDuration > 0", Category = "Parrot|Character|Stats"))
	bool bStunMidAir = false; 

	// A duration that the player is invulnerable after being hit
	UPROPERTY(BlueprintReadWrite, EditDefaultsOnly, meta = (ClampMin = "0.0", UIMin = "0.0", Category = "Parrot|Character|Stats"))
	float HitInvulnerabilityDuration = 0.0f; 
	UPROPERTY(BlueprintReadOnly, Category = "Parrot|Player|Powerups")
	bool bIsSpeedPowerupActive;  
	FTimerHandle TimerHandle_SpeedPowerup; 
protected:
	// Called when the game starts or when spawned
	virtual void BeginPlay() override;
	virtual void CharacterDeath() override;
	void StopSpeedPowerup();

	// Called when the hit stun timer has completed
	void StopHitStun();
	void StopHitInvulnerability();
	UFUNCTION(BlueprintCallable, Category = "Parrot|Player|Powerups")
	void AddHitpoints(int32 PointsToAdd); 
	UFUNCTION(BlueprintCallable, Category = "Parrot|Player|Powerups")
	void ActivateSpeedPowerup(float Duration, float MaxSpeedMultiplier); 
	UFUNCTION(BlueprintImplementableEvent, Category = "Parrot|Player|Powerups")
	void OnSpeedPowerupActivated(float Duration); 
	UFUNCTION(BlueprintImplementableEvent, Category = "Parrot|Player|State")
	void OnEnemyJump(); 
};

1. 反射系统（Reflection System）和 UHT(Unreal Header Tool)系统

文章标题中列举的宏实际上隶属于两个系统：

• 反射系统（Reflection System）：UCLASS、UPROPERTY、UFUNCTION
• UHT(Unreal Header Tool)系统：GENERATED_BODY

1.1 反射系统（Reflection System）

UCLASS(Abstract, Blueprintable)
class PARROT_API AParrotPlayerCharacter : public AParrotCharacterBase
{
	UPROPERTY(BlueprintReadOnly, Category = "Parrot|Player|Powerups")
	bool bIsSpeedPowerupActive;  
	UFUNCTION(BlueprintImplementableEvent, Category = "Parrot|Player|State")
	void OnEnemyJump(); 
public:
	...
}

再聊宏之前，不得不先说说UE C++的反射系统（Reflection System）。虚幻引擎的设计初衷是面向AAA级甚至元宇宙级的超大型游戏项目，它之所以选择C++作为其最核心也是最底层的开发语言，其根本原因就是“快”！这个快是针对程序运行时(Runtime)而言的，在极致压榨机器性能，让程序跑得“快”这方面，称C++为程序语言之王是当之无愧的。但凡事皆有利弊，相对于诸如C#,Python等很多更现代的语言来讲，C++损失了很多使用上的便利性以及增加了开发难度和门槛，比如：垃圾回收（GC）、元数据（Metadata）访问等等方面，并且虚幻还需要让C++代码定义的属性以及函数，可以在关卡编辑器中显示，以及和蓝图的各种交互等，这一切都是纯C++很难完成的。

于是，为了虚幻引擎团队为了降低开发难度并提高安全性、稳定性，在纯C++基础上借助C++的宏机制构建了一套反射系统。有了它，UE C++在保持运行时高效率的同时大大提升了开发体验。因此，当初学者看到那些奇怪的宏，没有必要感到压力，相反再后续的开发中这些宏会给我们提供很大的便利。如果你使用过C#，这些反射宏的使用体验很类似于C#中的Attribute。

在文章的后半部分，我会列举出常用的反射宏使用方法。

1.2 UHT(Unreal Header Tool)系统

虚幻头文件分析工具（UHT） 是虚幻引擎的一种自定义解析和代码生成工具。UHT可为虚幻引擎（UE）的 UObject 系统解析并生成代码。虚幻引擎中的代码编译分两个阶段进行：虚幻编译工具（Unreal Build Tool (UBT)） 会调用UHT，后者将解析C++头文件，获取与虚幻引擎相关的类元数据，并生成自定义代码，以实现各种与UObject相关的功能。UBT会调用配置的C++编译器来编译结果。总的来说，对于初学者，我们把UHT理解为一中帮我们生成必要的C++代码的工具就可以了。

UCLASS(Abstract, Blueprintable)
class PARROT_API AParrotPlayerCharacter : public AParrotCharacterBase
{
	GENERATED_BODY()
public:
	...
}

这里的宏GENERATED_BODY()就是告诉UHT，让它来为我们生成一些必要的辅助代码。

2. 属性说明符UPROPERTY

参考官方文档：UPROPERTY

3. 函数说明符UFunction

参考官方文档：UFunction