游戏引擎 / 系统课时

用C++扩展Gameplay类

用C++扩展Gameplay类

可维护的 UE5 Gameplay 通常不是“全部写蓝图”或“全部写 C++”,而是让 C++ 提供稳定规则、数据边界和可复用能力,再让蓝图负责资源选择与关卡级组合。这样既保留蓝图迭代速度,又避免核心逻辑分散在大量节点图中。

学习目标

  • 创建可被蓝图继承和调用的 C++ Gameplay 类
  • 使用 UPROPERTY 与 UFUNCTION 控制 C++ 到蓝图的暴露边界
  • 用 BlueprintNativeEvent 建立“C++ 默认实现 + 蓝图可覆盖”的扩展点

先划清C++与蓝图的职责

一个实用分工是:C++ 管规则,蓝图管配置。比如交互机关的“是否允许重复触发、触发后如何改变状态”适合放在 C++;具体使用哪套 Mesh、音效、粒子和关卡参数则交给蓝图子类。

C++Gameplay基类与蓝图子类的职责关系

C++ 暴露给蓝图的成员越少,长期维护通常越轻松。不要把每个私有变量都标成 BlueprintReadWrite;优先提供语义明确的函数,让蓝图通过受控入口修改状态。

常见选择可以这样理解:

标记 适合场景
EditDefaultsOnly 允许在蓝图类默认值中配置,但实例运行时不随意改
BlueprintReadOnly 蓝图需要读取状态,但不应直接写入
BlueprintCallable 蓝图可以主动调用一段 C++ 行为
BlueprintNativeEvent C++ 有默认实现,同时允许蓝图覆盖扩展

创建一个可继承的Gameplay基类

在 UE5 编辑器中可以通过 Tools > New C++ Class 创建 Actor 子类,再替换为下面的 GameplaySwitch 实现。示例不使用 Tick,而是把一次交互建模为 Activate(),这比每帧检查是否被触发更直接。

cpp
// 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"));
}

预期输出

text
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 基础实现。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用C++扩展Gameplay类

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通