🚀 虚幻引擎5 (UE5) C++ 入门：Mac 环境配置与核心技能实现 (Dash)

本文记录了在 macOS (M 系列芯片/Sonoma) 环境下，从创建 C++ 项目到配置开发环境，并用 C++ 实现了核心技能——短距离冲刺 (Dash) 的全过程。

---

0. 关键环境配置与兼容性

在 Mac 上进行 UE C++ 开发，最大的挑战是 Xcode 编译器版本 与 UE 引擎版本 的兼容性。

| 元素 | 你的稳定配置 | 关键原因 | | :--- | :--- | :--- | | 操作系统 | macOS Sonoma 14.3.1 | | | Xcode | 15.3 | | | UE 引擎 | 5.3.2 | 经验证，这是与 M2/Sonoma/Xcode 15.3 兼容性最佳的稳定版本。 | | VS Code | C/C++ 扩展 | 仅作为代码编辑器，编译由 Xcode/UBT 完成。 |

---

1. 解决开发环境的“红色波浪线”与编译问题

新创建的 C++ 项目在 VS Code 中会报告大量宏错误（UCLASS 等报红），且无法通过内置任务编译。

1.1 解决 VS Code IntelliSense 报错 (红线)

这是因为 VS Code 的默认解析器无法理解 UE 的反射系统。

1. 关闭 VS Code。
2. 生成项目文件： 在 Finder 中，右键点击 .uproject 文件 -> Services -> Generate Xcode Project (目的是刷新 VS Code 配置)。
3. 修改 VS Code 设置 (解决报红)：
   • 在 VS Code 中，打开 Settings (Cmd + ,)。
   • 搜索 C_Cpp.intelliSenseEngine，将其值从 Default 更改为 Tag Parser。

1.2 解决 Mac 上的编译问题 (UBT 脚本)

由于内置任务失效，我们需绕过 VS Code，手动运行 UE 的构建脚本。

1. 在 VS Code 终端中，进入 UE 引擎的构建脚本目录（请替换你的引擎路径）：

   cd "/Users/Shared/Epic Games/UE_5.3/Engine/Build/BatchFiles"
   

2. 执行 Mac 专用的构建脚本：
   • 注意： 替换为你的 .uproject 文件的完整路径。

   ./Mac/Build.sh CPPEditor Mac Development '/Users/builder/Documents/Unreal Projects/CPP/CPP.uproject'
   

---

2. C++ 基础：角色类与编码规范

• 角色类名： ACPPCharacter (A-Actor 前缀)。
• 文件： CPPCharacter.h (声明) 和 CPPCharacter.cpp (实现)。

2.1 UE C++ 核心规范

| 概念 | 语法 | 目的 | | :--- | :--- | :--- | | 反射系统 | UCLASS(), UPROPERTY(), UFUNCTION() | 允许蓝图和编辑器识别和使用 C++ 代码。 | | 内存类型 | FTimerHandle, TArray, FVector | 使用 UE 专有结构体/容器，确保被垃圾回收器 (GC) 正确管理。 | | 头文件顺序 | #include "[文件名].generated.h" | 必须是头文件中最后一行 #include。 |

---

3. C++ 核心技能实现：短距离冲刺 (Dash)

Dash 技能利用 UE 的 LaunchCharacter (施加瞬时力) 和 FTimerHandle (计时器管理冷却)。

3.1 CPPCharacter.h (声明)

 // CPPCharacter.h (在 .generated.h 之前引入 TimerManager.h)

    private: 
    // UPROPERTY 暴露给蓝图和细节面板
    UPROPERTY(EditAnywhere, Category = "Action|Dash")
    float DashPower = 1500.0f; 

    UPROPERTY(EditAnywhere, Category = "Action|Dash")
    float DashCooldown = 1.5f; 

    FTimerHandle DashTimerHandle;
    
    UFUNCTION()
    void Dash();

    void ResetDashCooldown();

3.2 CPPCharacter 实现

// CPPCharacter.cpp (在文件底部)

void ACPPCharacter::Dash()
{
    // 检查冷却状态
    if (!GetWorldTimerManager().IsTimerActive(DashTimerHandle))
    {
        const FVector ForwardVector = GetActorForwardVector();
        
        // LaunchCharacter 施加瞬时力
        LaunchCharacter(ForwardVector * DashPower, true, false); 

        // 设置计时器：在 DashCooldown 秒后调用 ResetDashCooldown
        GetWorldTimerManager().SetTimer(DashTimerHandle, this, &ACPPCharacter::ResetDashCooldown, DashCooldown, false);
    }
}

void ACPPCharacter::ResetDashCooldown()
{
    GetWorldTimerManager().ClearTimer(DashTimerHandle);
}

4. Enhanced Input 最终配置

这是将 C++ 代码连接到玩家按键的最后一步，所有操作都在 UE 编辑器中完成。

1.创建 Input Action (IA) 资产： 新建 Input Action 资产，命名为 IA_Dash。

2.角色蓝图设置：

打开角色蓝图 (BP_PlayerCharacter)。

在 细节面板 的 Input 分类中，将 Dash Action 槽位设置为 IA_Dash。

3.Input Mapping Context (IMC) 配置：

找到项目中的 IMC_Default 资产。

添加新映射：Action 选择 IA_Dash，Key 选择你需要的按键（例如 Left Shift）。