UE5中TSoftObjectPtr的使用详解

文章目录

前言
一、TSoftObjectPtr 的核心特性
二、基本用法示例
- 2.1 声明与赋值
二、同步加载资源
三、异步加载示例
四、蓝图中的TSoftObjectPtr
五、注意事项
六、对比硬引用
总结

前言

在UE5中，TSoftObjectPtr 是一种重要的资源管理工具，它允许开发者以“软引用”的方式引用资源（如纹理、模型、蓝图等），而不会强制资源立即加载到内存中。这种机制特别适用于需要动态加载资源的场景，例如开放世界中的流送系统或按需加载资源。以下是详细说明和具体示例：

一、TSoftObjectPtr 的核心特性

延迟加载：仅保存资源路径，不主动加载资源。
安全性：自动处理资源卸载后的引用失效问题。
兼容性：支持蓝图和C++，可与AsyncLoad配合实现异步加载。
内存优化：避免不必要的内存占用，按需加载。

二、基本用法示例

2.1 声明与赋值

在C++类中声明一个TSoftObjectPtr成员变量，引用一个纹理资源：

// Header File (.h)
#pragma once

#include "CoreMinimal.h"
#include "UObject/SoftObjectPtr.h"

UCLASS()
class YOURPROJECT_API AMyActor : public AActor
{
    GENERATED_BODY()

public:
    UPROPERTY(EditAnywhere, Category = "Resources")
    TSoftObjectPtr<UTexture2D> SoftTexture; // 声明软引用纹理

    void LoadAndUseTexture();
};

在编辑器细节面板中，可以直接为SoftTexture指定一个纹理资源（如T_ExampleTexture）。

二、同步加载资源

通过**LoadSynchronous()**同步加载资源：

// Source File (.cpp)
#include "MyActor.h"

void AMyActor::LoadAndUseTexture()
{
    UTexture2D* Texture = SoftTexture.LoadSynchronous(); // 同步加载
    if (Texture)
    {
        // 使用纹理，例如赋值给材质
        UE_LOG(LogTemp, Warning, TEXT("Texture loaded: %s"), *Texture->GetName());
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to load texture!"));
    }
}

三、异步加载示例

使用StreamableManager异步加载资源，避免阻塞主线程：

// Header File (.h)
#include "Engine/StreamableManager.h"

// 类声明中添加：
public:
    void AsyncLoadTexture();

private:
    FStreamableManager StreamableManager;
    TSharedPtr<FStreamableHandle> AsyncLoadHandle;

// Source File (.cpp)
void AMyActor::AsyncLoadTexture()
{
    if (SoftTexture.IsPending()) // 检查资源是否未加载
    {
        FSoftObjectPath TexturePath = SoftTexture.ToSoftObjectPath();
        AsyncLoadHandle = StreamableManager.RequestAsyncLoad(
            TexturePath,
            FStreamableDelegate::CreateUObject(this, &AMyActor::OnTextureLoaded)
        );
    }
}

void AMyActor::OnTextureLoaded()
{
    UTexture2D* Texture = SoftTexture.Get(); // 获取已加载的资源
    if (Texture)
    {
        UE_LOG(LogTemp, Warning, TEXT("Async texture loaded: %s"), *Texture->GetName());
    }
    AsyncLoadHandle->ReleaseHandle(); // 释放句柄
}

四、蓝图中的TSoftObjectPtr

在蓝图中，可以直接使用Soft Object Reference节点：

在蓝图中添加一个Soft Object Reference变量（类型选择Texture或其他资源）。
使用Load Asset节点异步加载资源。
通过On Loaded事件处理加载完成后的逻辑。

五、注意事项

有效性检查：使用**IsValid()或IsPending()**检查资源状态。
引用管理：确保资源在需要时未被垃圾回收（可通过**UPROPERTY()**保持引用）。
路径转换：通过**ToSoftObjectPath()**获取资源路径字符串。
性能优化：避免频繁同步加载，优先使用异步。

六、对比硬引用

硬引用：直接使用UPROPERTY(EditAnywhere) UTexture2D* Texture;，资源会随关卡加载。
软引用：TSoftObjectPtr，仅在需要时加载。

总结

TSoftObjectPtr 是UE5中实现资源动态加载的核心工具之一，合理使用可显著优化内存占用和启动时间。结合AsyncLoad和FStreamableManager，能够高效管理大规模资源，特别适合开放世界、动态内容加载等场景。

秒客网