当前位置：首页 > news >正文

UE_C++ —— Gameplay Classes

news 来源：原创 2025/9/18 7:08:54

一，Adding Classes

二，Class Headers

Class Declaration

Class Specifiers

Metadata Specifiers

三，Class Implementation

Class Constructor

引擎中每个游戏类都由一个类头文件（.h）和一个类源文件（.cpp）构成；类头包含类和类成员（如变量和函数）的声明，而在类源文件中是类功能的实现；引擎中的类拥有一个标准化的命名方案，通过首字母或前缀即可立即明了其为哪种类；

Prefix	Meaning
A	从可生成的游戏对象的基础类进行延伸；它们是 Actor，可直接生成到世界场景中；
U	从所有游戏对象的基础类进行延伸；它们无法被实例到世界场景中，必须从属于 Actor；总体而言，它们是相似组件的对象；

一，Adding Classes

主菜单Tools > New C++ Class...是一种快速简便的方法，将本机C++代码类添加到项目中，以便根据需要扩展功能；这会将纯内容项目转换为代码项目；确保安装了兼容版本的Visual Studio；

二，Class Headers

引擎中的游戏类通常拥有单独且唯一的类头文件；通常这些文件的命名与其中定义的类相匹配，减去 A 或 U 前缀，并使用 .h 文件扩展名；因此，AActor 类的类头文件命名为 Actor.h；虽然 Epic 代码遵循这些规则，但当前引擎中类名称和源文件名之间不存在正式关系；

游戏类的类头文件使用标准 C++ 语法，并结合专门的宏，以简化类、变量和函数的声明过程；

在每个游戏类头文件的顶端，需要包含生成的头文件（自动创建）；因此在 ClassName.h 的顶端必须出现以下行：

#include "ClassName.generated.h"

Class Declaration

类声明定义类的名称、其继承的类，以及其继承的函数和变量；类声明还定义了其他引擎和编辑器的特定行为（通过类说明符和元数据）；

UCLASS([specifier, specifier, ...], [meta(key = value, key = value, ...)])
class ClassName : public ParentName
{GENERATED_BODY()
}

声明包含一个类的标准 C++ 类声明；在标准声明之上，描述符（如类说明符和元数据）将被传递到 UCLASS 宏；它们用于创建被声明类的 UClass，可被看作引擎对类的专有表达；此外，GENERATED_BODY() 宏必须被放置在类体的最前方；

Class Specifiers

Class Specifier	Effect
Abstract	将类声明为"抽象基类"，不可向关卡中添加此类的Actor；对于单独存在时没有意义的类，此说明符非常有用；如，`ATriggerBase`基类是抽象类，而`ATriggerBox`子类不是抽象类，可以放置在关卡；
AdvancedClassDisplay	强制类的所有属性仅在显示在细节面板的"高级（Advanced）"部分；
AutoCollapseCategories=(Category1, Category2, ...)	使父类上的 AutoExpandCategories 说明符列出类别的效果无效；
AutoExpandCategories=(Category1, Category2, ...)	为此类的对象指定应自动在编辑器属性窗口中展开的一个或多个类别；要自动展开未使用类别声明的变量，请使用声明变量的类的名称；
Blueprintable	将此类公开为用于创建蓝图的可接受基类；默认为`NotBlueprintable`，除非继承时就并非如此；此说明符由子类继承；
BlueprintType	将此类公开为可用于蓝图中变量的类型；
ClassGroup=GroupName	指示在编辑器的Actor浏览器中启用组视图（Group View）时，Actor浏览器应在指定的 `GroupName` 中包含此类及此类的所有子类；
CollapseCategories	指示此类的属性不应划分到编辑器属性窗口的类别中；此说明符会传播到子类，可由`DontCollapseCategories`说明符覆盖；
Config=ConfigName	指示此类可在配置文件（`.ini`）中存储数据；如存在任何使用`config`或`globalconfig`说明符声明的类属性，此说明符将使这些属性存储在指定的配置文件中；此说明符会传播到所有子类并且无法使其无效，但是子类可通过重新声明`config`说明符并提供不同的`ConfigName`来更改配置文件；常见的`ConfigName`值是"Engine"、"Editor"、"Input"和"Game"；
Const	此类中的所有属性和函数都是`const`并且导出为`const`；此说明符由子类继承；
ConversionRoot	根转换，将子类限制为仅可沿层级向上转换为第一个根类的子类；
CustomConstructor	阻止构造函数声明自动生成；
DefaultToInstanced	此类的所有实例都被认为是"实例化的"；实例化的类（组件）将在构造时被复制；此说明符由子类继承；
DependsOn=(ClassName1, ClassName2, ...)	列出的所有类将先于此类被编译；可使用单个`DependsOn`行（以逗号分隔）来标识多个依赖类，或可通过为每个类使用单独的`DependsOn`行来指定多个依赖类；当某个类使用在另一个类中声明的结构体或枚举时，这非常重要，因为编译器仅知道它已编译了类中的哪些部分；
Deprecated	此类已弃用，序列化时将不保存此类的对象；此说明符由子类继承；
DontAutoCollapseCategories=(Category, Category, ...)	使列出的类别的继承自父类的`AutoCollapseCategories`说明符无效；
DontCollapseCategories	使继承自基类的`CollapseCatogories`说明符无效；
EditInlineNew	指示可从编辑器"属性（Property）"窗口创建此类的对象，而非从现有资源引用；默认行为是仅可通过"属性（Property）"窗口指定对现有对象的引用。此说明符会传播到所有子类；子类可通过 `NotEditInlineNew` 说明符覆盖它；；
HideCategories=(Category1, Category2, ...)	列出一个或多个应该对用户完全隐藏的分类；要隐藏未使用类别声明的属性，请使用声明变量的类的名称；此说明符会传播到子类；
HideDropdown	阻止此类在属性窗口组合框中显示；
HideFunctions=(Category1, Category2, ...)	让指定分类中的所有函数都对用户完全隐藏；
HideFunctions=FunctionName	将提到的函数对用户完全隐藏；
Intrinsic	指示此类直接在C++中声明，无 Unreal Header Tool 生成的样板；请勿在新类上使用此说明符；
MinimalAPI	导致仅导出此类的类型信息，以供其他模块使用；可以此类为目标进行强制转换，但此类的函数无法被调用（除了使用内联方法）；这可以缩短编译时间，因为没有针对无需从其他模块访问其所有函数的类导出一切；
NoExport	指示此类的声明不应包含在由标头生成器自动生成的C++头文件中；必须在单独的头文件中手动定义该C++类声明；仅对本地类有效；请勿对新类使用此说明符；
NonTransient	使继承自基类的`Transient`说明符无效；
NotBlueprintable	指定此类不是可用于创建蓝图的可接受基类，此为默认说明符，将由子类继承，
NotPlaceable	使继承自基类的`Placeable`说明符无效；指示不可以在编辑器中将此类的对象放置到关卡、UI场景或蓝图中；
PerObjectConfig	此类的配置信息将按对象存储，在`.ini`文件中，每个对象都有一个分段，根据对象命名，格式为`[ObjectName ClassName]`；此说明符会传播到子类；
Placeable	指示可在编辑器中创建此类，而且可将此类放置到关卡、UI场景或蓝图（取决于类类型）中；此标志会传播到所有子类；子类可使用`NotPlaceable`说明符覆盖此标志；
ShowCategories=(Category1, Category2, ...)	使列出的类别的继承自基类的`HideCategories`说明符无效；
ShowFunctions=(Category1, Category2, ...)	在属性查看器中显示列出的类别中的所有函数；
ShowFunctions=FunctionName	在属性查看器中显示指定的函数；
Transient	从不将属于此类的对象保存到磁盘；当与播放器或窗口等本质上不持久的特定种类的原生类配合使用时，它非常有用；此说明符会传播到子类，但是可由`NonTransient`说明符覆盖；
Within=OuterClassName	此类的对象无法在`OuterClassName`对象的实例之外存在；这意味着，要创建此类的对象，需要提供`OuterClassName`的一个实例作为其`Outer`对象；

Metadata Specifiers

Class Meta Tag	Effect
BlueprintSpawnableComponent	如其存在，组件类可由蓝图生成；
BlueprintThreadSafe	只在蓝图函数库上有效；此说明符将把此类中的函数在动画蓝图中的非游戏线程上标记为可调用；
ChildCannotTick	用于Actor和组件类；如本地类无法tick，那么基于此Actor或组件的蓝图生成类则无法tick，即使 `bCanBlueprintsTickByDefault` 为true也同样如此；
ChildCanTick	用于Actor和组件类；如本地类无法tick，那么可以覆盖基于此Actor或组件的蓝图生成类的 `bCanEverTick` 标签，即使 `bCanBlueprintsTickByDefault` 为false也同样如此；
DeprecatedNode	用于行为树节点，说明类已废弃，编译时将显示一条警告；
DeprecationMessage="Message Text"	如类已废弃，尝试编译使用此类的蓝图时，其将被添加到标准废弃警告；
DisplayName="Blueprint Node Name"	此节点在蓝图中的命名将被此处提供的值所取代，而非代码生成的命名；
DontUseGenericSpawnObject	不使用蓝图中的Generic Create Object节点来生成类的一个对象；此说明符只有在用于既非Actor又非ActorComponent的BluprintType类时才有意义；
ExposedAsyncProxy	在 Async Task 节点中公开此类的一个代理对象；
IgnoreCategoryKeywordsInSubclasses	用于让一个类的首个子类忽略所有继承的 `ShowCategories` 和 `HideCategories` 说明符；
IsBlueprintBase="true/false"	说明此类是否为创建蓝图的一个可接受基类，与 `UCLASS` 说明符、`Blueprintable` 或 `NotBlueprintable` 相似；
KismetHideOverrides="Event1, Event2, .."	不允许被覆盖的蓝图事件的列表；
ProhibitedInterfaces="Interface1, Interface2, .."	列出与类不兼容的接口；
RestrictedToClasses="Class1, Class2, .."	由蓝图函数库类使用，用于限制列表中命名类的用法；
ShortToolTip="Short tooltip"	完整提示文本过长时使用的简短提示文本，如父类选取器对话；
ShowWorldContextPin	说明放置在此类拥有的图表中的蓝图节点必须显式其World情景引脚（即使其通常状态下为隐藏也同样如此），因为此类的对象无法被用作World情景；
UsesHierarchy	说明类使用层级数据。用于实例化"细节"面板中的层级编辑功能；
ToolTip="Hand-written tooltip"	覆盖从代码注释自动生成的提示文本；
ScriptName="DisplayName"	在将此类、属性或函数导出到脚本语言时使用的名称；可以包含以启用的名称作为以分号分隔的额外条目；

三，Class Implementation

所有游戏类必须使用 GENERATED_BODY 宏才能正确实现；这是在定义类及其所有变量和函数的类头（.h）文件中完成的；最佳方法是使类源和头文件的命名与实现的类相匹配，减去 A 或 U 前缀；因此，AActor 类的源文件命名为 Actor.cpp，其头文件命名为 Actor.h；对编辑器中"Add C++ Class"菜单选项创建的类而言，此操作将自动进行；

源文件（.cpp）必须囊括包含 C++ 类声明的头文件（.h），C++ 类声明通常为自动生成，但也可手动生成（如有必要）；如，AActor 类的 C++ 声明在 EngineClasses.h 头文件中自动生成；这意味着 Actor.cpp 文件必须包括 EngineClasses.h 文件或轮流包含的另一个文件；总体而言只包含游戏项目的头文件，其中包含了游戏项目中游戏类的标头；以 AActor 和 EngineClasses.h 为例，其中包含了 EnginePrivate.h 标头，此标头则包含了 Engine.h - Engine 项目的头文件 - 而该头文件又包含 EngineClasses.h 头文件；

#include "EnginePrivate.h"

Class Constructor

UObjects 使用 Constructors 设置属性和其他变量的默认值，并执行其他必要的初值设定；类构造函数通常放置在类实现文件中，如 AActor::AActor 构造函数位于 Actor.cpp 中；

注，部分构造函数可能以每个模块为基础放置在一个特殊的"constructors"文件中；如 AActor::AActor 构造函数可能存在于 EngineConstructors.cpp 中；这是自动转换过程的结果，从之前 DEFAULTS 块的使用到构造函数的使用；它们将随时间被移至其相应的类源文件；

也可以将构造函数内联放置在类头文件中；然而，如果构造函数在类头文件中，UClass 必须结合 CustomConstructor 说明符进行声明，因为这阻止了自动代码生成器在标头中创建构造函数声明；

Constructor Format

UObject 构建函数最基本的形式如下所示：

UMyObject::UMyObject()
{// 在此处初始化 Class Default Object 属性。
}

该构造函数初始化类默认对象（CDO），CDO 是类的新实例所基于的原版；此外还有一个次要构造函数，支持一个特殊的属性调整结构：

UMyObject::UMyObject(const FObjectInitializer& ObjectInitializer): Super(ObjectInitializer)
{// Initialize CDO properties here.
}

虽然以上构造函数实际上并不执行任何初始化，但引擎已将所有字段初始化为零、NULL，或其默认构造函数实现的任意值；然而，写入构建函数的任意初始化代码将被应用至 CDO，因此将被复制到引擎中正确创建的对象新实例上，正如 CreateNewObject 或 SpawnActor；

被传入构造函数的 FObjectInitializer 参数除被标记为常数外，还可通过嵌入可变函数进行配置，以覆写属性和子对象；被创建的 UObject 将受到这些变更的影响，这可用于变更注册属性或组件的数值；

AUDKEmitterPool::AUDKEmitterPool(const FObjectInitializer& ObjectInitializer): Super(ObjectInitializer.DoNotCreateDefaultSubobject(TEXT("SomeComponent")).DoNotCreateDefaultSubobject(TEXT("SomeOtherComponent")))
{// Initialize CDO properties here.
}

在上例中，超类将在其构建函数中创建名为"SomeComponent"和"SomeOtherComponent"的子对象，但由于 FObjectInitializer 的原因，该操作将不会执行；在下例中，SomeProperty 在 CDO 中将默认为 26，因此在 AUTDemoHUD 的每个新实例中均为如此；

AUTDemoHUD::AUTDemoHUD()
{// 在此处初始化 CDO 属性。SomeProperty = 26;
}

Constructor Statics and Helpers

为更负责的数据类型设置数值（尤其是类引用、命名和资源引用）时，需要在构造函数中定义并实例化一个 ConstructorStatics 结构体，以保存所需的诸多属性数值；ConstructorStatics 结构体在构造函数首次运行时才会被创建；在随后的运行上它只会复制一个指针，使其处理速度极快；ConstructorStatics 被创建时，数值将被指定到结构体成员，以便稍后在构建函数上指定数值到实际属性时进行访问；

ContructorHelpers 是 ObjectBase.h 中定义的特殊命名空间；ObjectBase.h 包含用于执行构建函数特定常规操作的助手模板；如为资源或类寻找引用、以及创建并寻找组件的助手模板；

Asset References

理想状态下，类中的资源引用并不存在；硬编码资源引用很脆弱，优选方法是使用蓝图配置资源属性；然而，仍然完全支持硬编码引用；不需要在每次构造对象时搜索资源，因此这些搜索只执行一次；一个静态结构体可确保只执行一次资源搜索：

ConstructorHelpers::FObjectFinder 通过 StaticLoadObject 为特定的 UObject 寻找引用；它常用于引用存储在内容包中的资源；如未找到对象，则报告失败；

ATimelineTestActor::ATimelineTestActor()
{// Structure to hold one-time initializationstruct FConstructorStatics{ConstructorHelpers::FObjectFinder<UStaticMesh> Object0;FConstructorStatics(): Object0(TEXT("StaticMesh'/Game/UT3/Pickups/Pickups/Health_Large/Mesh/S_Pickups_Base_Health_Large.S_Pickups_Base_Health_Large'")){}};static FConstructorStatics ConstructorStatics;// Property initializationStaticMesh = ConstructorStatics.Object0.Object;
}

Class References

ConstructorHelpers::FClassFinder 为特定的 UClass 寻找引用；如类未找到，则报告失败；

APylon::APylon(const class FObjectInitializer& ObjectInitializer):Super(ObjectInitializer)
{// 进行一次性初始化的结构static FClassFinder<UNavigationMeshBase> ClassFinder(TEXT("class'Engine.NavigationMeshBase'"));if (ClassFinder.Succeeded()){NavMeshClass = ClassFinder.Class;}else{NavMeshClass = nullptr;}
}

在许多情况下，可只使用 USomeClass::StaticClass()，绕开复杂的全部 ClassFinder；如，在多数情况下均可使用以下方法：

NavMeshClass = UNavigationMeshBase::StaticClass();

对跨模块的引用而言，使用 ClassFinder 法较好；

Components and Sub-Objects

在构造函数中还可创建组件子对象并将其附着到 actor 的层级；生成一个 actor 时，将从 CDO 复制其组件；为确保组件固定被创建、被销毁和被正确地垃圾回收，构建函数中创建的每个组件的指针应被存储在拥有类的一个 UPROPERTY 中；

UCLASS()
class AWindPointSource : public AActor
{GENERATED_BODY()
public:UPROPERTY()UWindPointSourceComponent* WindPointSource;UPROPERTY()UDrawSphereComponent* DisplaySphere;
};AWindPointSource::AWindPointSource()
{// 创建一个新组件并对其命名。WindPointSource = CreateDefaultSubobject<UWindPointSourceComponent>(TEXT("WindPointSourceComponent0"));// 将新组件设为该 actor 的根组件，如已存在一个根组件，则将其附着到根上。if (RootComponent == nullptr){RootComponent = WindPointSource;}else{WindPointSource->AttachTo(RootComponent);}// 再创建一个组件。将其附着到刚才创建的第一个组件上。DisplaySphere = CreateDefaultSubobject<UDrawSphereComponent>(TEXT("DrawSphereComponent0"));DisplaySphere->AttachTo(RootComponent);// 在新组件上设置一些属性。DisplaySphere->ShapeColor.R = 173;DisplaySphere->ShapeColor.G = 239;DisplaySphere->ShapeColor.B = 231;DisplaySphere->ShapeColor.A = 255;DisplaySphere->AlwaysLoadOnClient = false;DisplaySphere->AlwaysLoadOnServer = false;DisplaySphere->bAbsoluteScale = true;
}通常没有必要对属于父类的组件进行修改。然而，在任何 `USceneComponent`（包括根组件）上调用 `GetAttachParent`、`GetParentComponents`、`GetNumChildrenComponents`、`GetChildrenComponents` 和 `GetChildComponent` 即可获得当前所有附着组件（包括父类创建的组件）的列表。

一，Adding Classes

二，Class Headers

Class Declaration

Class Specifiers

Metadata Specifiers

三，Class Implementation

Class Constructor

相关文章：