自动关联目录：资源加载与异步加载

加载的本质是一次磁盘 IO + 一次反序列化。前者慢（毫秒到百毫秒级），后者占用主线程。所以"加载卡顿"几乎总是在主线程上做了同步加载。

一句话定位：所有能在后台做的加载都该异步；所有异步加载都要有人持有 handle，否则加载完立刻被 GC。

四种方式

// 同步（会卡）
UTexture2D* Tex = LoadObject<UTexture2D>(nullptr, TEXT("/Game/Icons/Sword.Sword"));

// 异步（推荐）
FSoftObjectPath Path(TEXT("/Game/Icons/Sword.Sword"));
TSharedPtr<FStreamableHandle> Handle =
    UAssetManager::GetStreamableManager().RequestAsyncLoad(Path,
        [Path]()
        {
            UTexture2D* Tex = Cast<UTexture2D>(Path.ResolveObject());
        });

软引用

UPROPERTY(EditAnywhere)
TSoftObjectPtr<UTexture2D> Icon;       // 编辑器可见，运行时不加载

// 需要时
Icon.LoadSynchronous();                 // 同步
UAssetManager::GetStreamableManager().RequestAsyncLoad(Icon.ToSoftObjectPath(), Callback);

把 TSoftObjectPtr 换成硬引用（UTexture2D*）的代价是：外层资产一加载，它就被一起加载。角色数据里硬引用几十张贴图 = 打开角色界面就要等几十个 IO。

Handle 与保活

这是异步加载最容易出错的地方：加载完成后，如果你不持有任何强引用，对象会被 GC 回收。

class UMyComponent : public UActorComponent
{
    UPROPERTY()                              // 1. UPROPERTY 构成 GC 引用边
    TArray<TObjectPtr<UTexture2D>> LoadedTextures;

    TSharedPtr<FStreamableHandle> Handle;    // 2. 持有 handle，加载期间保持有效

    void Load()
    {
        Handle = UAssetManager::GetStreamableManager().RequestAsyncLoad(Paths,
            [this](){ Handle->GetLoadedAssets(LoadedTextures); });
    }
};

典型 bug：异步回调里只把对象塞进 TArray<UTexture2D*>（未标 UPROPERTY），回调结束后对象消失，表现为"偶尔加载不出来"。

卡顿排查

// 找出是不是同步加载：在同步加载处打断点，或开日志
LogStreaming Verbose

关键命令：

FlushAsyncLoading() 是卡顿之王：它会阻塞主线程直到所有异步加载完成。加载界面结束后立刻调它，就是一次大卡顿。

预加载策略

// 分帧预加载：每帧请求一个，避免一次性把所有 IO 压到一帧
void UPreloader::Tick(float DT)
{
    if (PendingIndex < PendingPaths.Num())
    {
        UAssetManager::GetStreamableManager().RequestAsyncLoad(PendingPaths[PendingIndex++]);
    }
}

卸载

"内存降不下来"的常见原因：引用没断干净。用 obj refs name=XXX 看谁还在持有它。

常见坑