UE5资源异步加载流程分析

概述

本文档详细分析 UE5 中 FStreamableManager 的资源异步加载流程，从 RequestAsyncLoad 开始到回调执行结束的完整过程。通过深入分析源码，我们将理解主线程与加载线程的交互机制，以及资源依赖的处理方式。

核心概念

关键类和结构

FStreamableManager：UE5 中负责管理资源异步加载的核心类
FStreamableHandle：跟踪单个异步加载请求的状态和回调
FStreamable：内部用于跟踪单个资源的加载状态
FSoftObjectPath：软引用路径，用于指向尚未加载的资源

主要流程组件

请求发起：通过 RequestAsyncLoad 或相关方法发起异步加载请求
请求处理：StartHandleRequests 处理加载请求
资源加载：StreamInternal 执行实际的资源加载逻辑
回调处理：加载完成后通过回调通知主线程
依赖处理：自动处理资源间的依赖关系

完整流程分析

请求发起阶段

从 RequestAsyncLoadInternal 函数开始：

1
2
3
4
5
6
7
TSharedPtr<FStreamableHandle> FStreamableManager::RequestAsyncLoadInternal(
    TArray<FSoftObjectPath>&& TargetsToStream, 
    FStreamableDelegate&& DelegateToCall, 
    TAsyncLoadPriority Priority, 
    bool bManageActiveHandle, 
    bool bStartStalled, 
    FString&& DebugName)

主要步骤：

创建加载句柄：创建 FStreamableHandle 对象来跟踪加载请求
设置回调：将用户提供的回调函数存储到句柄中
验证资源路径：检查并清理无效的资源路径
管理句柄：如果需要，将句柄添加到活动句柄列表
启动加载：调用 StartHandleRequests 开始处理加载请求

加载处理阶段

StartHandleRequests 函数处理实际的加载请求：

1
void FStreamableManager::StartHandleRequests(TSharedRef<FStreamableHandle> Handle)

主要步骤：

遍历资源：对每个请求的资源调用 StreamInternal
跟踪现有流：将返回的 FStreamable 对象添加到列表中
检查已加载资源：对于已经在内存中的资源，直接标记为完成

资源加载核心

StreamInternal 是资源加载的核心实现：

1
2
3
4
FStreamable* FStreamableManager::StreamInternal(
    const FSoftObjectPath& InTargetName, 
    TAsyncLoadPriority Priority, 
    TSharedRef<FStreamableHandle> Handle)

主要步骤：

检查内存中是否存在：如果资源已在内存中，直接返回
创建流对象：如果是新资源，创建 FStreamable 对象
同步加载检查：在某些情况下（如初始化加载、构造函数中）执行同步加载
异步加载：调用 LoadPackageAsync 发起异步加载请求
设置回调：配置加载完成后的回调函数

回调处理阶段

加载完成后，会调用 AsyncLoadCallback 函数：

1
void FStreamableManager::AsyncLoadCallback(FSoftObjectPath TargetName, UPackage* Package)

主要步骤：

获取流对象：根据资源路径找到对应的 FStreamable 对象
标记加载完成：设置 bAsyncLoadRequestOutstanding = false
查找内存中的资源：调用 FindInMemory 查找加载完成的资源
检查完成请求：调用 CheckCompletedRequests 检查是否所有请求都已完成

完成检查和回调执行

CheckCompletedRequests 函数检查加载请求是否完成，并执行相应的回调：

主要步骤：

遍历相关句柄：检查所有引用该资源的 FStreamableHandle
标记完成状态：对于已完成的资源，更新句柄的完成状态
执行回调：当所有资源都加载完成时，执行用户提供的回调函数

主线程与加载线程的交互

线程职责划分

线程类型	职责	关键操作
主线程	发起加载请求，处理回调	创建加载请求，执行完成回调
加载线程	执行实际的资源加载	读取磁盘，解析包文件，加载资源

交互机制

请求发起：主线程调用 LoadPackageAsync 发起加载请求
任务调度：LoadPackageAsync 将加载任务提交到异步加载系统
后台加载：加载线程在后台执行实际的加载操作
完成通知：加载完成后，通过 FLoadPackageAsyncDelegate 回调通知主线程
回调执行：主线程在 AsyncLoadCallback 中处理加载完成的资源

同步点

虽然加载过程是异步的，但在某些情况下会强制同步：

初始化阶段：在游戏初始化时，某些资源需要同步加载
构造函数中：在对象构造函数中发起的加载请求会同步执行
强制同步：当设置了 bForceSynchronousLoads 标志时

资源依赖的处理

依赖加载机制

UE5 的包加载系统会自动处理资源依赖：

包依赖分析：当加载一个资源时，系统会分析其依赖的其他资源
递归加载：自动加载所有依赖的资源
依赖图管理：构建和管理资源间的依赖关系图

具体流程

主资源加载：发起对主资源的加载请求
依赖分析：加载系统分析主资源的依赖项
依赖加载：自动为所有依赖项创建加载请求
加载顺序：根据依赖关系确定加载顺序
完成通知：所有依赖都加载完成后，才会通知主资源加载完成

依赖处理示例

场景：加载一个包含材质和纹理的静态网格

发起加载：请求加载静态网格资源 StaticMesh'/Game/Meshes/Sphere.Sphere'
依赖分析：加载系统发现该网格使用了材质 Material'/Game/Materials/Metal.Metal'
材质加载：自动加载材质资源
纹理加载：发现材质依赖于纹理 Texture2D'/Game/Textures/Metal_Albedo.Metal_Albedo'，自动加载纹理
完成顺序：纹理 → 材质 → 静态网格
回调执行：当所有资源都加载完成后，执行用户提供的回调

代码流程详解

核心流程图

  flowchart TD
    A[RequestAsyncLoadInternal] --> B[创建FStreamableHandle]
    B --> C[StartHandleRequests]
    C --> D[StreamInternal]
    D --> E{资源是否在内存中?}
    E -->|是| F[直接返回]
    E -->|否| G{是否需要同步加载?}
    G -->|是| H[StaticLoadObject]
    G -->|否| I[LoadPackageAsync]
    I --> J[加载线程执行]
    J --> K[AsyncLoadCallback]
    H --> L[CheckCompletedRequests]
    K --> L
    L --> M{所有资源加载完成?}
    M -->|是| N[执行用户回调]
    M -->|否| O[继续等待]

关键代码解析

请求创建与初始化

1
2
3
4
5
6
// 创建新的加载句柄
TSharedRef<FStreamableHandle> NewRequest = MakeShareable(new FStreamableHandle());
NewRequest->CompleteDelegate = MoveTemp(DelegateToCall);
NewRequest->OwningManager = this;
NewRequest->RequestedAssets = MoveTemp(TargetsToStream);
NewRequest->DebugName = MoveTemp(DebugName);

这段代码创建了一个新的 FStreamableHandle 对象，并设置了回调函数、资源路径等信息。

资源加载核心

1
2
3
4
5
6
7
// 异步加载资源
Existing->RequestId = LoadPackageAsync(PackagePath,
    NAME_None /* PackageNameToCreate */,
    FLoadPackageAsyncDelegate::CreateSP(Handle, &FStreamableHandle::AsyncLoadCallbackWrapper, TargetName),
    PKG_None /* InPackageFlags */,
    INDEX_NONE /* InPIEInstanceID */,
    Priority /* InPackagePriority */);

这段代码调用 LoadPackageAsync 发起异步加载请求，并设置回调函数。

回调处理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
void FStreamableManager::AsyncLoadCallback(FSoftObjectPath TargetName, UPackage* Package)
{
    check(IsInGameThread());

    FStreamable* Existing = FindStreamable(TargetName);

    UE_LOG(LogStreamableManager, Verbose, TEXT("Stream Complete callback %s"), *TargetName.ToString());
    if (Existing)
    {
        if (Existing->bAsyncLoadRequestOutstanding)
        {
            Existing->bAsyncLoadRequestOutstanding = false;
            if (!Existing->Target)
            {
                FindInMemory(TargetName, Existing, Package);
            }

            CheckCompletedRequests(TargetName, Existing);
        }
        // ...
    }
}

这段代码处理加载完成的回调，标记加载状态，并检查是否所有请求都已完成。

实际应用示例

基本异步加载

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// 基本异步加载示例
TArray<FSoftObjectPath> AssetsToLoad;
AssetsToLoad.Add(FSoftObjectPath("StaticMesh'/Game/Meshes/Sphere.Sphere'"));
AssetsToLoad.Add(FSoftObjectPath("Material'/Game/Materials/Metal.Metal'"));

UStreamableManager* StreamableManager = UStreamableManager::Get();
StreamableManager->RequestAsyncLoad(
    AssetsToLoad,
    FStreamableDelegate::CreateLambda([]() {
        UE_LOG(LogTemp, Log, TEXT("所有资源加载完成!"));
        // 在这里使用加载完成的资源
    }),
    FStreamableManager::AsyncLoadHighPriority,
    false,
    TEXT("ExampleLoad"));

带句柄的异步加载

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
// 带句柄的异步加载示例
UStreamableManager* StreamableManager = UStreamableManager::Get();
TSharedPtr<FStreamableHandle> LoadHandle = StreamableManager->RequestAsyncLoad(
    FSoftObjectPath("StaticMesh'/Game/Meshes/Sphere.Sphere'"),
    FStreamableDelegate::CreateLambda([]() {
        UE_LOG(LogTemp, Log, TEXT("资源加载完成!"));
    }),
    TEXT("SphereLoad"));

// 可以使用句柄检查加载状态
if (LoadHandle.IsValid())
{
    if (LoadHandle->HasLoadCompleted())
    {
        UE_LOG(LogTemp, Log, TEXT("加载已完成!"));
    }
    else if (LoadHandle->HasLoadFailed())
    {
        UE_LOG(LogTemp, Error, TEXT("加载失败!"));
    }
}

依赖加载示例

1
2
3
4
5
6
7
8
9
// 依赖加载示例 - 加载一个包含多个依赖的资源
UStreamableManager* StreamableManager = UStreamableManager::Get();
StreamableManager->RequestAsyncLoad(
    FSoftObjectPath("Blueprint'/Game/Blueprints/Character.Character'"),
    FStreamableDelegate::CreateLambda([]() {
        UE_LOG(LogTemp, Log, TEXT("角色蓝图及其所有依赖加载完成!"));
        // 这里可以安全地使用角色蓝图及其所有依赖资源
    }),
    TEXT("CharacterLoad"));

性能优化建议

加载策略优化

批量加载：将多个相关资源合并到一个加载请求中，减少加载开销
优先级设置：根据资源的重要性设置合适的加载优先级
预加载：在适当的时机预加载即将使用的资源
异步加载：尽可能使用异步加载，避免阻塞主线程

内存管理

及时释放：不再使用的资源及时通过 ReleaseHandle 释放
依赖分析：分析并优化资源依赖关系，减少不必要的加载

错误处理

加载失败处理：添加加载失败的回调处理
超时处理：对于关键资源，添加加载超时检测
错误日志：添加详细的错误日志，便于排查加载问题

常见问题与解决方案

加载失败

问题：资源加载失败

解决方案：

检查资源路径是否正确
确保资源文件存在于指定位置
检查资源依赖是否完整
查看日志获取详细错误信息

加载缓慢

问题：资源加载速度过慢

解决方案：

优化资源大小和复杂度
使用合适的压缩格式
实现资源预加载

内存占用过高

问题：加载过多资源导致内存占用过高

解决方案：

及时释放不再使用的资源
实现资源池管理
考虑使用动态资源加载策略
监控内存使用情况，及时调整加载策略

总结

UE5 的 FStreamableManager 提供了一个强大而灵活的资源异步加载系统，通过以下机制实现高效的资源管理：

主线程与加载线程分离：主线程发起请求，加载线程执行实际加载，通过回调机制通知完成
自动依赖处理：加载系统自动处理资源间的依赖关系，确保所有依赖都被正确加载
灵活的加载策略：支持同步和异步加载，可根据不同场景选择合适的加载方式
详细的状态跟踪：通过 FStreamableHandle 提供详细的加载状态信息

通过合理使用 FStreamableManager，开发者可以实现高效的资源管理，提升游戏的加载速度和运行性能。

参考资料

虚幻引擎资产异步加载 | 虚幻引擎 5.7 文档 | Epic Developer Community
UE5 源码：Engine/Source/Runtime/Engine/Private/StreamableManager.cpp
UE5 源码：Engine/Source/Runtime/CoreUObject/Private/UObject/AsyncLoad.cpp

本文档基于 UE5.5 源码分析，不同版本可能存在细微差异。