很多做过一段时间蓝图的朋友第一次接触Unreal Engine5的C往往会有点懵明明蓝图里拖一拖就有的东西换成C怎么要写一大串其实换个角度看C更像是去掉了图形包装的蓝图逻辑还是一样的只是你得按编译器能懂的方式去表达。我自己的经验是如果先用蓝图把一个功能跑通再去看对应的C写法会轻松很多。这篇笔记就是给准备认真啃UE5 C的同学准备的内容围绕最常用、最容易踩坑的基础知识展开从工程环境到类生命周期从组件到输入从蓝图交互到常见编译报错尽量用大白话把原理和操作串在一起。不管你是纯蓝图使用者想补上底层能力还是刚入行想投游戏开发岗位这份笔记都能帮你少走几步弯路。1. 先从工程和编辑器说起搞明白C代码在UE5里是怎么被“接”进去的1.1 创建一个C工程的正确姿势在启动器里创建工程时引擎会问你要不要带C基础代码这一步其实只决定模板自带的初始类。更关键的是工程生成之后你会看到根目录下有一个.uproject文件旁边有一个Source文件夹里面放着你工程的核心代码。只要这个文件在你就可以在编辑器的工具栏上随时点“编译”。第一次创建C工程时引擎会生成一个与工程同名的模块这个模块就是所有代码的编译单元。我习惯的流程是先在启动器里选一个现成模板比如第三人称或空白哪怕是用蓝图模板创建的工程只需要在项目设置里重新添加C类引擎也会自动帮你生成并配置好Source相关文件。所以“蓝图工程能不能写C”这个问题答案是可以的只是前期准备里引擎会多跑一次编译过程把代码模块接进来。创建完成后你会在Source/工程名/下看到.h和.cpp文件。如果打开.build.cs文件能看到这个模块依赖了哪些引擎模块。刚入门的话不需要动它等后面用到AI、UMG、Online子系统时再回来添加相应依赖。1.2 编辑器怎么知道你的代码变动了在UE5的旧版本里每次改完头文件新增一个类经常要重启编辑器才能识别新版本会弹窗提示“需要重新编译”点一下等它编译好再继续操作就行。通常我写的流程是在编辑器的“工具→新C类”里创建类填好名字和路径。用你喜欢的外部IDE打开刚生成的.h和.cpp开始改代码。回到UE编辑器按CtrlAltF11或者工具栏上的编译按钮等底部状态栏提示编译成功。编译完成后如果涉及蓝图挂接或类修改一般要在“内容浏览器”里右键重新加载蓝图或者直接重启编辑器。一个小建议改头文件里类的继承关系或新增UPROPERTY后偶尔会出现“蓝图文件打开时编译失败”的情况因为蓝图实例依赖的老结构还占着内存。这时候把所有蓝图编辑器关掉再编译十有八九就好了。如果你的美术同事在旁边急着用编辑器这个细节能帮你避免很多尴尬。2. 先背下这套对象模型UObject、AActor、UActorComponent到底谁管谁2.1 UObject是万物之源但你不能随便new它在UE5里包括关卡内实体、资产、资源绝大多数对象都继承自UObject。但UObject和普通C类的最大区别是它由引擎的垃圾回收系统管理你不能直接写new AActor()而是要使用引擎提供的工厂函数或SpawnActor。为什么因为UObject要被引擎的反射系统、序列化系统、网络复制系统同时盯住只有通过引擎那套创建流程这些系统才能正确地记录对象引用。你写一个纯功能类如果不需要存在于关卡中也不想被引擎当作资产那可以直接继承UObject。比如一个计算伤害的工具类写成UCLASS()UObject派生然后通过NewObjectUFoo()创建。它不会被自动销毁而是等引用消失后由GC回收。大多数情况下我们的可写类不是AActor就是UActorComponent所以UObject这个底层概念知道它的存在和创建约束就行。2.2 AActor与UActorComponent的寿命分工关卡里的手机、敌人、子弹、触发点能摆在Level里的东西大部分都是AActor。AActor本身像一个空壳它负责出现在关卡中、被旋转移动、被放进流送关卡。而真正干活的往往是它身上的组件UActorComponent。我要特别强调一句可能会被忽视的话组件不是Actor组件没有自己的Transform除非是SceneComponent子类。比如你给一个门写了一个交互组件UMyDoorInteractComponent如果它不是USceneComponent的子类那它就没有位置、方向这些数据它只能在“逻辑层面”上工作。同样的道理AActor自带一个RootComponent这个根组件一般为空或是一个USceneComponent所有可视化表现组件都要挂到它下面Actor被移动时根组件带动整个物体树一起动。所谓的“生命周期函数”指的是引擎在特定时机调用的回调BeginPlay()当Actor进入关卡并且游戏开始时被调用适合做初始化、设置初始状态。EndPlay()被销毁或因为关卡切换退出时调用适合释放资源、关闭定时器。Tick(float DeltaTime)每帧都会调用适合处理连续变化比如超出距离自动销毁、平滑移动。OnConstruction(const FTransform Transform)在Actor被创建、蓝图放置、修改参数时都会调用比较适合生成预览。实操上新手最爱犯的错误是在构造函数里面去获取其他Actor的引用或者做需要等引擎初始化完毕的操作。原因很简单构造函数执行时别人可能还没开始BeginPlay你拿到的引用很可能是空指针。正确做法是把引用查找放到BeginPlay或PostInitializeComponents里。2.3 反射宏UPROPERTY与UFUNCTION为什么这么重要写C时你会频繁看到UPROPERTY()和UFUNCTION()挂在成员变量和成员函数上面。这东西不是装饰是给“编辑器-蓝图-C”这个桥梁打下手的。比如一个成员变量UPROPERTY(EditAnywhere, BlueprintReadWrite, Category MySettings) float MoveSpeed 600.0f;如果没有UPROPERTY这个变量几乎不会被蓝图和编辑器看到而当某一天你改完它却发现变量没出现在细节面板里别怀疑一定漏了这个宏。加上EditAnywhere它出现在“细节”面板不动代码就能调值加上BlueprintReadWrite蓝图里可以读它也可以改它。函数也一样一个普通C函数蓝图是看不到的但是如果你写上UFUNCTION(BlueprintCallable, Category MyFunctions) void DoSomething();蓝图就能直接调用这个函数。注意逻辑C写功能蓝图调表现大多数项目的分层就是这样的。3. 第一个自定义Actor从建类到加组件的全流程3.1 手把手在编辑器和IDE里创建一个Pickup类假设我们要做“捡物品”的逻辑一个可以放在地面上的圆形胶囊体玩家碰到它物品消失并给玩家加积分。第一步在编辑器里选择Tools → New C Class父类选择AActor命名Pickup。生成后你会得到Pickup.h和Pickup.cpp。接下来打开头文件把默认的代码扩展一下// Pickup.h #pragma once #include CoreMinimal.h #include GameFramework/Actor.h #include Pickup.generated.h UCLASS() class MYGAME_API APickup : public AActor { GENERATED_BODY() public: APickup(); protected: virtual void BeginPlay() override; UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category Components) class USceneComponent* Root; UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category Components) class UStaticMeshComponent* Mesh; UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category Components) class UCapsuleComponent* Collision; UFUNCTION() void OnBeginOverlap(UPrimitiveComponent* OverlappedComp, AActor* OtherActor, UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult SweepResult); };在构造函数里创建根组件和两个子组件// Pickup.cpp #include Pickup.h #include Components/StaticMeshComponent.h #include Components/CapsuleComponent.h APickup::APickup() { // 根组件为空的场景组件保证Actor有根 Root CreateDefaultSubobjectUSceneComponent(TEXT(Root)); RootComponent Root; // 碰撞胶囊体负责触发Overlap Collision CreateDefaultSubobjectUCapsuleComponent(TEXT(Collision)); Collision-SetupAttachment(Root); Collision-SetCapsuleSize(50.0f, 80.0f); // 可视化网格体方便在关卡里看到它 Mesh CreateDefaultSubobjectUStaticMeshComponent(TEXT(Mesh)); Mesh-SetupAttachment(Collision); Mesh-SetCollisionEnabled(ECollisionEnabled::NoCollision); }这里重点解释一下为什么碰撞和网格分开网格体负责“看起来像”胶囊体负责“碰得到”。很多新手把碰撞直接设在网格上一旦模型不对称玩起来就会觉得明明没碰到却触发并捡走了。使用专用碰撞组件你可以在细节面板里把它的视觉化显示调成半透明调起来省心很多。生命周期函数里再绑定Overlap事件void APickup::BeginPlay() { Super::BeginPlay(); if (Collision) { Collision-OnComponentBeginOverlap.AddDynamic(this, APickup::OnBeginOverlap); } } void APickup::OnBeginOverlap(UPrimitiveComponent* OverlappedComp, AActor* OtherActor, UPrimitiveComponent* OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult SweepResult) { if (OtherActor OtherActor-IsA(ACharacter::StaticClass())) { // 在这里触发捡拾逻辑 Destroy(); } }注意我在OnBeginOverlap里加了一个判断只有角色类碰到才响应防止两个Pickup互相触发无限销毁。初学者容易忽略事件里会传来一堆无关Actor导致Debug时怪现象层出不穷。3.2 编译与挂载到关卡的注意事项写完后回到编辑器编译。编译不报错后点击“Compile”或热启动然后去“内容浏览器”里找到你的Pickup右键Create Blueprint创建BP_Pickup。这样做的原因是C里的APickup是原生类你无法直接在场景里改它的网格体参数而蓝图子类可以。进入BP_Pickup找到组件列表里的Mesh组件给它指定一个静态网格资源比如引擎内置的立方体或球体。然后把碰撞预设改成OverlapAll或者至少保证Generate Overlap Events勾选了胶囊体才会发事件。挂到关卡时直接把BP_Pickup拖进场景即可。运行游戏用自带第三人称模板的角色走进它物品会消失。如果你发现没反应先检查角色的胶囊体是否开启Generate Overlap Events其次检查Pickup类是否真的在构造函数里绑定了事件这两个是高频踩坑点。4. 输入绑定与常用的静态调用让你的类真正能干活4.1 在C里绑定按键而不是在蓝图里拖蓝图里每个角色都有一个InputComponent你可以在事件图表里拖出“InputAction”事件。C里做这件事也简单但前两步会与项目配置有关在“项目设置→输入→Action Mappings / Axis Mappings”里定义好名字比如Jump或MoveForward。在你的角色类继承自ACharacter里重写SetupPlayerInputComponent// AMyCharacter.h virtual void SetupPlayerInputComponent(class UInputComponent* PlayerInputComponent) override; // AMyCharacter.cpp #include Components/InputComponent.h void AMyCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent) { Super::SetupPlayerInputComponent(PlayerInputComponent); PlayerInputComponent-BindAction(Jump, IE_Pressed, this, ACharacter::Jump); PlayerInputComponent-BindAxis(MoveForward, this, AMyCharacter::MoveForward); PlayerInputComponent-BindAxis(MoveRight, this, AMyCharacter::MoveRight); }BindAxis这个函数会自动把你角色身上的CharacterMovementComponent里的移动向量计算好你只需在函数里调用void AMyCharacter::MoveForward(float Value) { if (Controller Value ! 0.f) { FRotator Rotator Controller-GetControlRotation(); FRotator YawRotator(0, Rotator.Yaw, 0); FVector Direction FRotationMatrix(YawRotator).GetUnitAxis(EAxis::X); AddMovementInput(Direction, Value); } }我一开始也是直接把蓝图里的Add Movement Input翻译成C但发现一个小坑蓝图节点直接传World Direction但C里的AddMovementInput输入参数是方向向量和强度方向向量必须是世界空间的单位向量所以上面代码里我把控制器的旋转取Yaw分量后再用旋转矩阵算出X轴方向。否则角色斜着走时会不自然。4.2 常用静态函数UGameplayStatics和UKismetSystemLibrary写蓝图的时候你可能已经熟悉了GetWorldTimerManager、SpawnActor、GetPlayerController这类的节点它们的底层对应C里的两个静态类UGameplayStatics里到处都有GetPlayerPawn、GetPlayerController、SpawnActor、OpenLevel、GetGameInstance。比如在C里生成一个新的Pickupif (PickupClass) { FVector SpawnLoc GetActorLocation() FVector(0, 0, 100); FRotator SpawnRot FRotator::ZeroRotator; FActorSpawnParameters SpawnParams; SpawnParams.Owner this; GetWorld()-SpawnActorAPickup(PickupClass, SpawnLoc, SpawnRot, SpawnParams); }GetWorld()并不是所有地方都可以随便调用一般只有UObject在拥有OuterWorld上下文时才拿得到比如Actor和Component里都能直接用GetWorld()。如果你在自己的UObject子类里不小心写成GetWorld()可能返回空此时需要手动保存WorldContextObject。UKismetSystemLibrary对应蓝图里的常见工具箱Delay、PrintString、GetActorBounds、DrawDebugLine等。C里写UKismetSystemLibrary::PrintString(this, FString::Printf(TEXT(Text%f), 1.0f));就可以在屏幕上打印信息。调试时非常实用。注意PrintString的this参数是用来确定世界上下文的不要传空指针。4.3 定时器比Delay更好用的延时方式蓝图里Delay节点会让整个逻辑流程图卡住C里推荐用定时器FTimerHandle来延时执行函数。因为它不会阻塞你可以在一个函数里马上返回之后引擎回调你指定的函数。定义在头文件UPROPERTY() FTimerHandle RespawnTimerHandle;实现void APickup::Respawn(float InDelay) { // 保存当前使用的类或变量然后销毁自己 int ChosenIndex 0; GetWorldTimerManager().SetTimer(RespawnTimerHandle, [this, ChosenIndex]() { // lambda里可以塞逻辑也可以调用其他函数 OnRespawnFinished(ChosenIndex); }, InDelay, false); }使用lambda表达式可以很方便地捕获局部变量但一定要注意lambda里如果使用了this而Actor可能被销毁定时器不会自动取消回调还会执行然后就会访问野指针。所以在Actor的EndPlay里最好加一句GetWorldTimerManager().ClearTimer(RespawnTimerHandle);5. 蓝图和C的桥接让美术和策划能顺手调参数5.1 用BlueprintNativeEvent实现C默认逻辑蓝图可覆盖纯蓝图项目里事件图表的自定义能力很强。C里想兼顾“默认实现”和“可被蓝图重写”最常见的是用BlueprintNativeEvent。示例头文件UFUNCTION(BlueprintNativeEvent, Category Pickup) void OnPickupCollected(ACharacter* Collector);Cpp文件里这样实现后缀为_Implementation的函数void APickup::OnPickupCollected_Implementation(ACharacter* Collector) { // 默认逻辑加分销毁 AddScore(Collector, 10); Destroy(); }在蓝图里当你重写这个函数时图表里会多出一个节点OnPickupCollected。右击节点能选择“在蓝图里覆盖”之后你的蓝图实现会替换默认C实现除非你调用父类版本。这就是NativeEvent的含义C里提供一份基本实现蓝图可以完全重写兼得两者。5.2 用BlueprintImplementableEvent定义纯蓝图事件如果你希望C里只提供一个“钩子”然后所有逻辑都写在蓝图里用BlueprintImplementableEventUFUNCTION(BlueprintImplementableEvent, Category Pickup) void NotifyHitByPlayer(AActor* OtherActor);在C里直接调用NotifyHitByPlayer(OtherActor);蓝图那边只要实现了同名事件就会执行蓝图里的逻辑。假如蓝图没有实现调用时什么都不会发生也不会报错。这种灵活性非常有用比如共享一个C基类给不同关卡的不同敌人用敌人被击杀后播放什么特效由关卡蓝图自己决定。5.3 动态多播委托C事件与蓝图的“广播”蓝图里的“Event Dispatcher”对应的C版本是动态多播委托DECLARE_DYNAMIC_MULTICAST_DELEGATE。假如你要写一个“血量变化”的事件DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnHealthChanged, float, NewHealth); UCLASS() class UHealthComponent : public UActorComponent { GENERATED_BODY() public: UPROPERTY(BlueprintAssignable, Category Health) FOnHealthChanged OnHealthChanged; void ApplyDamage(float Damage) { Health - Damage; OnHealthChanged.Broadcast(Health); } };在蓝图上你拿到HealthComponent后细节面板或事件图表里能看到OnHealthChanged可以从它Blueprint绑定事件。C这边用Broadcast广播蓝图那边则用“Bind Event”节点。值得注意的是C动态委托广播的参数类型不能是普通C结构体必须是支持蓝图反射的类型比如float、bool、AActor*或带UPROPERTY的USTRUCT结构。6. 新手最常遇到的编译报错与开发建议6.1 这五类报错是刚起步时的高频灾难每次线上答疑几乎一半问题都是编译报错。我总结了两类最典型的第一类头文件编译顺序错误。比如在A类头文件里用了B类指针但是只前向声明了class B;然后你在A.cpp里要用B的成员却忘了#include B.h。编译器就会提示“使用未定义类型”。解决方式头文件能前向声明就绝不非要去include完整头文件只在.cpp里include就行。第二类UPROPERTY类型不支持。比如想用TMapFString, UAnyClass*作为UPROPERTY变量C可以编译但编辑器里普通版本可能不显示。TMap也是支持的但Value是原始指针类型时要注意标记UPROPERTY()的TMap在三者间处理时有不小限制用TSubclassOf或硬引用更稳妥。第三类函数未声明宏就蓝图调用。有人觉得在C里定义了个函数蓝图节点上应该自动出现结果死活找不到。绝大多数是因为少写了UFUNCTION(BlueprintCallable)。注意BlueprintCallable和BlueprintImplementableEvent位置别写反。第四类重写父类函数时忘了加Super。比如重写BeginPlay时如果漏掉Super::BeginPlay();父类初始化逻辑全断掉会出现不可捉摸的表现比如组件没绑定事件。加Super::BeginPlay()是一个稳定习惯。第五类配对声明和定义的宏不一致。头文件函数写的是UFUNCTION(BlueprintPure)cpp里函数名一致就行但参数列表大小写不同导致编译错误。最简单的方式是让IDE帮你生成函数定义。6.2 给持续更新笔记的编码习惯建议既然这个笔记要“持续更新”本身也说明UE5 C是学不完的。我给自己的学习路径定几个原则你可以参考每个C文件主题单一尽量不要把多个功能都堆在同一个Actor里。组件化是UE5推荐的思路宁可多拆几个组件也不要一个类里写4000行。每个变量都考虑加注释特别是不明显的坐标偏移和数值调整否则三个月后的自己根本看不懂。C侧尽量少做表现层的参数调整把可调数值全部暴露成EditAnywhere的变量测试时直接改场景细节面板不用反复编译。打Log比打断点方便特别是在服务器和客户端逻辑分离的网络环境下打断点经常只看到Server或Client某一端。用UE_LOG(LogTemp, Warning, TEXT(...))输出关键节点的状态是排查问题的最快方式。每次有新想法先想清楚这个类要不要被蓝图继承。如果不打算让策划改动逻辑就写成C类如果后续可能出现多个变体那就做好Blueprintable的基类。我自己在实际项目中体会到UE5的C和虚幻编辑器更像一对齿轮刚接触时咬合不顺但一旦熟悉了UPROPERTY、UFUNCTION、UCLASS这几个宏以及生成、初始化、销毁的流程写起来的速度并不会比蓝图慢太多。而且很多性能敏感、逻辑复杂的系统用C实现确实能避免蓝图节点爆炸的维护噩梦。上面这些基础笔记是我一开始从蓝图转C时踩了无数次坑之后的总结后续想到新的坑和实用写法我会继续补充进去。
