游戏引擎 / 系统课时
用C++扩展Gameplay类
用C++扩展Gameplay类
可维护的 UE5 Gameplay 通常不是“全部写蓝图”或“全部写 C++”,而是让 C++ 提供稳定规则、数据边界和可复用能力,再让蓝图负责资源选择与关卡级组合。这样既保留蓝图迭代速度,又避免核心逻辑分散在大量节点图中。
学习目标
- 创建可被蓝图继承和调用的 C++ Gameplay 类
- 使用
UPROPERTY与UFUNCTION控制 C++ 到蓝图的暴露边界 - 用
BlueprintNativeEvent建立“C++ 默认实现 + 蓝图可覆盖”的扩展点
先划清C++与蓝图的职责
一个实用分工是:C++ 管规则,蓝图管配置。比如交互机关的“是否允许重复触发、触发后如何改变状态”适合放在 C++;具体使用哪套 Mesh、音效、粒子和关卡参数则交给蓝图子类。

C++ 暴露给蓝图的成员越少,长期维护通常越轻松。不要把每个私有变量都标成 BlueprintReadWrite;优先提供语义明确的函数,让蓝图通过受控入口修改状态。
常见选择可以这样理解:
| 标记 | 适合场景 |
|---|---|
EditDefaultsOnly |
允许在蓝图类默认值中配置,但实例运行时不随意改 |
BlueprintReadOnly |
蓝图需要读取状态,但不应直接写入 |
BlueprintCallable |
蓝图可以主动调用一段 C++ 行为 |
BlueprintNativeEvent |
C++ 有默认实现,同时允许蓝图覆盖扩展 |
创建一个可继承的Gameplay基类
在 UE5 编辑器中可以通过 Tools > New C++ Class 创建 Actor 子类,再替换为下面的 GameplaySwitch 实现。示例不使用 Tick,而是把一次交互建模为 Activate(),这比每帧检查是否被触发更直接。
// GameplaySwitch.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "GameplaySwitch.generated.h"
class USceneComponent;
UCLASS(Blueprintable)
class AGameplaySwitch : public AActor
{
GENERATED_BODY()
public:
AGameplaySwitch();
UFUNCTION(BlueprintCallable, Category = "Gameplay")
void Activate();
UFUNCTION(BlueprintPure, Category = "Gameplay")
bool IsActivated() const
{
return bActivated;
}
protected:
UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "Gameplay")
TObjectPtr<USceneComponent> SceneRoot;
UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Gameplay")
bool bSingleUse = true;
UFUNCTION(BlueprintNativeEvent, Category = "Gameplay")
void OnActivated();
virtual void OnActivated_Implementation();
private:
UPROPERTY(VisibleInstanceOnly, Category = "Gameplay")
bool bActivated = false;
};
// GameplaySwitch.cpp
#include "GameplaySwitch.h"
#include "Components/SceneComponent.h"
AGameplaySwitch::AGameplaySwitch()
{
PrimaryActorTick.bCanEverTick = false;
SceneRoot = CreateDefaultSubobject<USceneComponent>(TEXT("SceneRoot"));
SetRootComponent(SceneRoot);
}
void AGameplaySwitch::Activate()
{
if (bSingleUse && bActivated)
{
UE_LOG(LogTemp, Display, TEXT("GameplaySwitch ignored duplicate activation"));
return;
}
bActivated = true;
UE_LOG(LogTemp, Display, TEXT("GameplaySwitch activated"));
OnActivated();
}
void AGameplaySwitch::OnActivated_Implementation()
{
UE_LOG(LogTemp, Display, TEXT("GameplaySwitch default C++ response"));
}预期输出
GameplaySwitch activated
GameplaySwitch default C++ response如果 bSingleUse 保持默认值 true,再次调用 Activate() 时会拒绝重复激活,并打印 GameplaySwitch ignored duplicate activation。
BlueprintNativeEvent 会生成可供蓝图覆盖的事件入口;C++ 默认实现写在 OnActivated_Implementation() 中。蓝图子类如果覆盖该事件,可以替换默认行为,也可以在蓝图中显式调用父级实现后再追加表现逻辑。
在蓝图子类里组合表现
编译成功后,以 AGameplaySwitch 创建蓝图子类,例如 BP_DoorSwitch。在蓝图默认值中决定 bSingleUse,添加 Static Mesh、Audio 等表现组件,并覆盖 OnActivated,把开门动画、声音或特效放到这个扩展点。
此时 Gameplay 调用方只需要拿到基类引用并执行 Activate()。它不需要知道具体蓝图使用什么 Mesh,也不应该直接修改 bActivated。这让关卡设计可以持续换资源,而核心状态规则仍由 C++ 统一维护。
验证继承边界是否清楚
把 BP_DoorSwitch 放进测试关卡,并从角色、关卡脚本或另一个交互对象调用它的 Activate()。第一次触发应进入激活状态并执行蓝图覆盖的 OnActivated;单次机关再次触发时应被 C++ 规则拒绝。
验证时重点看两个边界:第一,蓝图能否完成资源与表现配置而无需修改 C++;第二,蓝图是否无法绕过核心状态规则直接写私有数据。只要这两个边界成立,后续新增更多机关蓝图时,就能复用同一套稳定的 Gameplay 基础实现。