UE5中UBlueprintFunctionLibrary类详解

---

前言

在 Unreal Engine 5（UE5）中，UBlueprintFunctionLibrary 是一个用于在蓝图中暴露 C++ 静态函数的工具类。通过继承此类，开发者可以创建全局可访问的工具函数，让蓝图和 C++ 共享逻辑。以下是详细说明和代码示例：

---

一、核心作用

• 蓝图调用 C++ 函数：将 C++ 静态函数暴露给蓝图，无需创建对象实例。
• 代码复用：封装通用功能（如数学计算、数据转换、游戏逻辑工具等）。
• 跨模块访问：提供跨不同游戏系统的工具函数（如 AI、UI、存档等）。

二、创建子类示例

创建一个继承自 UBlueprintFunctionLibrary 的子类，并添加静态函数：

// MyBlueprintFunctionLibrary.h
#pragma once

#include "Kismet/BlueprintFunctionLibrary.h"
#include "MyBlueprintFunctionLibrary.generated.h"

UCLASS()
class MYPROJECT_API UMyBlueprintFunctionLibrary : public UBlueprintFunctionLibrary
{
    GENERATED_BODY()

public:
    // 示例：将两个向量相加
    UFUNCTION(BlueprintCallable, Category = "MyLibrary|Math")
    static FVector AddVectors(const FVector& A, const FVector& B);
};

// MyBlueprintFunctionLibrary.cpp
#include "MyBlueprintFunctionLibrary.h"

FVector UMyBlueprintFunctionLibrary::AddVectors(const FVector& A, const FVector& B)
{
    return A + B;
}

三、关键代码说明

• UFUNCTION 宏：标记函数为蓝图可调用。
  • BlueprintCallable：允许蓝图调用。
  • Category：在蓝图节点菜单中的分类。
• 静态函数：无需对象实例即可调用。
• 参数与返回值：需使用 UE 支持的类型（如 FVector, AActor*, int32 等）。

四、高级用法示例

4.1 带执行流程的函数

// 带执行引脚（输入/输出）的函数
UFUNCTION(BlueprintCallable, Category = "MyLibrary|Flow", meta = (ExpandEnumAsExecs = "Result"))
static void CheckHealth(float Health, EMyResult& Result);

4.2 纯函数（无执行引脚）

// 纯函数（无执行流程，仅计算）
UFUNCTION(BlueprintCallable, BlueprintPure, Category = "MyLibrary|Math")
static bool IsHealthLow(float Health);

4.3 参数默认值

UFUNCTION(BlueprintCallable, Category = "MyLibrary|Debug")
static void LogMessage(FString Message, FColor Color = FColor::White);

五、蓝图中的使用

1. 在蓝图中右键搜索函数名（如 “Add Vectors”）。
2. 拖拽节点并连接参数。

六、注意事项

• 静态函数限制：不能直接访问实例成员变量（需通过参数传递对象）。
• 性能：频繁调用的函数需注意优化（避免在每帧调用的函数中进行复杂计算）。
• 模块依赖：确保库类所在的模块在项目的 Build.cs 中被正确引用。

七、实际应用场景

• 数据转换：将 FVector 转换为 FString 用于调试。
• 游戏逻辑工具：计算伤害、生成随机位置等。
• 系统接口：访问存档系统或成就系统的静态接口。

八、完整代码示例

// 示例：检测角色是否在视野内
UFUNCTION(BlueprintCallable, Category = "MyLibrary|AI")
static bool IsActorVisible(AActor* Target, AActor* Viewer, float MaxDistance = 1000.0f);

bool UMyBlueprintFunctionLibrary::IsActorVisible(AActor* Target, AActor* Viewer, float MaxDistance)
{
    if (!Target || !Viewer) return false;

    FVector ViewerLocation = Viewer->GetActorLocation();
    FVector TargetLocation = Target->GetActorLocation();

    // 距离检测
    if (FVector::Distance(ViewerLocation, TargetLocation) > MaxDistance) return false;

    // 视线检测
    FHitResult HitResult;
    FCollisionQueryParams Params;
    Params.AddIgnoredActor(Viewer);

    GetWorld()->LineTraceSingleByChannel(
        HitResult,
        ViewerLocation,
        TargetLocation,
        ECC_Visibility,
        Params
    );

    return HitResult.GetActor() == Target;
}

通过 UBlueprintFunctionLibrary，开发者可以高效地打通 C++ 与蓝图之间的逻辑，提升项目的可维护性和开发效率。