自动关联目录：资产注册表与编辑器查询

1. 定位

资产注册表（Asset Registry）是"不用加载资产就能查资产"的索引：编辑器里的内容浏览器、引用查询、批量操作都靠它。

一句话定位：它解决的是"我知道有一批资产，但不想为了找它们把资产全加载进内存"。

2. 它存什么

内容	说明
资产路径与名称	`FPackageName` / `FAssetData`
资产类型	`UClass` 信息
标签（Tags）	从资产的序列化数据里提取的键值对
依赖关系	谁引用了谁（`GetDependencies`）
磁盘上的元数据	不需要加载就能读

关键：这些信息来自资产的序列化摘要，不加载完整对象——这是它快的原因，也是它信息有限的原因。

3. 常见用途

用途	说明
内容浏览器的搜索与过滤	编辑器侧
批量查找某类资产	如"找出所有武器数据资产"
引用关系查询	谁引用了这个资产（删除前的安全检查）
打包时的依赖分析	见 Cook 与打包流程
运行时加载前的枚举	配合 AssetManager

4. 用法

FAssetRegistryModule& ARM =
    FModuleManager::LoadModuleChecked<FAssetRegistryModule>("AssetRegistry");
IAssetRegistry& AR = ARM.Get();

// 扫描（编辑器内）
AR.ScanPathsSynchronous({ TEXT("/Game/Items") });

// 查询
FARFilter Filter;
Filter.ClassPaths.Add(UMyItemData::StaticClass()->GetClassPathName());
Filter.bRecursiveClasses = true;

TArray<FAssetData> Assets;
AR.GetAssets(Filter, Assets);

// 取标签值
FAssetDataValue Value;
AssetData.GetTagValue(TEXT("Rarity"), Value);

API	用途
`GetAssets(Filter)`	按条件查资产
`GetDependencies` / `GetReferencers`	依赖与反向依赖
`GetAssetByObjectPath`	精确取一个
`ScanPathsSynchronous`	同步扫描目录
`OnAssetAdded` / `OnAssetRemoved`	变更通知

5. 与 AssetManager 的关系

	Asset Registry	AssetManager
层	底层索引	上层的运行时管理
主要场景	编辑器工具、批量查询	运行时加载与打包
是否加载资产	否	是（按需）
PrimaryAsset	不区分	核心概念

运行时该用 AssetManager，不该直接用 Asset Registry——后者主要是编辑器工具链与打包期用的。详见 AssetManager 与 PrimaryAsset。

6. 代价与权衡

设计	收益	代价	什么时候不该用
注册表查询	不加载资产，极快	只有摘要信息，读不到完整属性	需要读属性就必须加载
异步扫描	不卡编辑器	结果延后到达	需要同步结果时改用同步扫描
自定义标签	可按业务维度过滤	要在资产序列化时写入	简单项目不必
依赖查询	安全删除、影响面分析	大项目查询较慢	偶尔用即可

7. 踩坑与排查

坑	现象	怎么验证
运行时直接用注册表	打包后可能不完整	改用 AssetManager
查询前没扫描	查不到新资产	`ScanPathsSynchronous` 或等待扫描完成
依赖异步扫描却同步用	结果为空	等扫描完成回调
想读的属性不是标签	读不到	只能加载资产后读
打包后某些查询失效	编辑器专用数据不在包里	区分编辑器/运行时路径
大项目批量查询慢	卡	加缓存、缩小过滤范围

8. 排查顺序

1. 查不到资产？→ 是否扫描过；过滤条件是否正确
2. 读不到属性？→ 该属性不是标签 → 必须加载资产
3. 打包后失效？→ 是否用了编辑器专用数据
4. 运行时需求？→ 改用 AssetManager
5. 慢？→ 缩小过滤范围、缓存结果

参考

AssetManager 与 PrimaryAsset · 资源加载与异步加载 · Cook 与打包流程
反射与 UHT（标签来自序列化数据）