unreal-cpp-gameplay

Unreal C++ 游戏玩法

编写正确的 UE5 游戏玩法 C++：将 C++ 连接到编辑器和蓝图的反射宏、Gameplay Framework 类的职责，以及模块依赖项。目标版本为 UE 5.8。

适用场景

• 创建 C++ 游戏玩法类（AActor、APawn、ACharacter、AGameModeBase、UActorComponent）、使用 UPROPERTY/UFUNCTION 暴露属性/函数、设置 GameMode 的默认类，或在 *.Build.cs 中添加模块依赖项时使用。
• 项目包含使用 UCLASS 的 Source/ 目录树，其中有 *.h/*.cpp 文件和 *.Build.cs 文件时使用。

不适用场景： 面向设计师的可视化逻辑 → unreal-blueprints。玩家输入绑定细节 → unreal-enhanced-input。AI 逻辑 → unreal-behavior-trees。本技能负责这些功能赖以构建的 C++ 类/反射基础。

核心工作流

1. 使用正确的前缀命名。 A = 派生自 Actor，U = 派生自 UObject/组件，F = 普通结构体，E = 枚举，I = 接口。前缀必须与基类匹配。
2. 使用反射宏声明类。 在类上方添加 UCLASS()，在类体第一行添加 GENERATED_BODY()，并将 #include "ClassName.generated.h" 作为头文件中的最后一条 include。
3. 使用 UPROPERTY 暴露数据（编辑器/蓝图可见性以及垃圾回收追踪），并使用 UFUNCTION 暴露行为（BlueprintCallable 等）。
4. 在构造函数中创建组件，使用 CreateDefaultSubobject<T>(TEXT("Name"))，并设置 RootComponent。
5. 了解框架职责： AGameModeBase 设置规则和默认类；APawn/ACharacter 是可控制的身体；APlayerController 是玩家的意志；UActorComponent 是可复用的行为。
6. 在 *.Build.cs 中添加模块依赖项（例如 EnhancedInput），否则会出现未解析符号的链接错误。
7. 验证：编译（函数体可使用 Live Coding Ctrl+Alt+F11；修改头文件/UPROPERTY 后需要完整重建），并检查类/属性是否出现在编辑器中。

模式

1. 最简 Actor 类（头文件 + 源文件）

// Pickup.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "Pickup.generated.h"          // MUST be the last include

UCLASS()
class MYGAME_API APickup : public AActor   // MYGAME_API = your module's export macro
{
    GENERATED_BODY()
public:
    APickup();

    // EditAnywhere = tweak per-instance & on the CDO; BlueprintReadWrite = BP get/set.
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category = "Pickup")
    int32 ScoreValue = 10;

    // UPROPERTY on a UObject* pointer is what keeps it from being garbage-collected.
    UPROPERTY(VisibleAnywhere)
    TObjectPtr<UStaticMeshComponent> Mesh;   // UE5: TObjectPtr instead of raw UStaticMeshComponent*

    UFUNCTION(BlueprintCallable, Category = "Pickup")
    void Collect();

protected:
    virtual void BeginPlay() override;
};

// Pickup.cpp
#include "Pickup.h"
#include "Components/StaticMeshComponent.h"

APickup::APickup()
{
    Mesh = CreateDefaultSubobject<UStaticMeshComponent>(TEXT("Mesh"));
    RootComponent = Mesh;                     // the mesh is this actor's root
}

void APickup::BeginPlay() { Super::BeginPlay(); }   // always call Super
void APickup::Collect()   { Destroy(); }

2. 设置默认类的 GameMode

// MyGameMode.cpp — set in the constructor so the engine spawns your classes.
AMyGameMode::AMyGameMode()
{
    DefaultPawnClass      = AMyCharacter::StaticClass();
    PlayerControllerClass = AMyPlayerController::StaticClass();
}

3. Build.cs 中的模块依赖项

// MyGame.Build.cs
PublicDependencyModuleNames.AddRange(new string[]
{
    "Core", "CoreUObject", "Engine", "InputCore", "EnhancedInput"
});

常见问题

• generated.h 不是最后一条 include 或缺失 — 会出现“Cannot find generated header”或“Expected an include”等编译错误。它必须是头文件中的最后一条 include。
• 忘记添加 GENERATED_BODY() — 会导致 UHT（Unreal Header Tool）错误；它必须是类体中的第一项。
• 没有 UPROPERTY 的原始 UObject* — 垃圾回收器无法发现它，可能会在你使用时将其销毁。使用 UPROPERTY 追踪每个 UObject 指针（在 UE5 中使用 TObjectPtr）。
• 使用 Live Coding 修改头文件/UPROPERTY — Live Coding 可处理函数体，但修改 UCLASS/UPROPERTY/头文件后需要完整重启编辑器并重新构建。
• 类前缀错误 — 将 Actor 命名为 UFoo（或将组件命名为 AFoo）会导致 UHT 出错；前缀必须与基类类型匹配。
• 链接时出现未解析的外部符号 — 提供该 API 的模块未添加到 Build.cs 的 PublicDependencyModuleNames 中。
• 重写 BeginPlay/Tick 等函数时未调用 Super:: — 会跳过引擎设置。

参考资料

• 关于 UActorComponent 的创建/附加、UPROPERTY 垃圾回收所有权规则（TObjectPtr、TArray<TObjectPtr<>>、AddToRoot）以及复制入门，请阅读 references/components-and-gc.md。
• 主要文档：“Unreal Engine CPP Quick Start”和“Gameplay Framework” （https://dev.epicgames.com/documentation/en-us/unreal-engine/gameplay-framework-in-unreal-engine）。

相关技能

• unreal-blueprints — 将 C++ 暴露给设计师；BP/C++ 互操作。
• unreal-enhanced-input — 在 C++ Pawn/Character 中绑定输入。
• unreal-behavior-trees — 由行为树驱动的 C++ AI 任务。