Building Subsystem¶

UBuildingSubsystem 是一个 UGameInstanceSubsystem，负责加载、缓存和查询项目中的 Building Data Asset。

它与 GameInstance 生命周期相同，可以跨关卡保留。世界中的建筑实体、Chunk 和运行时表现由 UBuildingWorldSubsystem 管理。

获取 Subsystem¶

蓝图¶

Get Game Instance Subsystem
→ Building Subsystem

C++¶

UBuildingSubsystem* BuildingSubsystem =
    GetGameInstance()->GetSubsystem<UBuildingSubsystem>();

if (!IsValid(BuildingSubsystem))
{
    return;
}

建筑资产查询¶

接口	说明
`GetAllBuildings`	获取全部已加载建筑资产。
`GetBuildingsByCategory`	根据分类获取建筑资产。
`GetBuildingDataByAssetId`	根据 Primary Asset ID 获取建筑资产。

GetAllBuildings¶

TArray<UBuildingDataAsset*> GetAllBuildings() const;

返回全部已加载的建筑数据资产。

GetBuildingsByCategory¶

TArray<UBuildingDataAsset*> GetBuildingsByCategory(
    FName Category
) const;

返回指定 Category 的建筑数据资产。

分类值来自 UBuildingDataAsset::Category。

GetBuildingDataByAssetId¶

UBuildingDataAsset* GetBuildingDataByAssetId(
    FPrimaryAssetId AssetId
) const;

返回指定 Primary Asset ID 对应的已加载建筑资产。未找到时返回 nullptr。

该接口常用于建筑创建、网络同步和存档恢复。

加载状态¶

接口	返回值	说明
`AreBuildingAssetsLoaded`	`bool`	是否全部加载完成。
`GetLoadProgress`	`float`	加载进度，范围为 `0.0` 至 `1.0`。
`GetLoadedBuildingCount`	`int32`	当前已加载数量。
`GetTotalBuildingCount`	`int32`	本次扫描到的总数量。

没有扫描到建筑资产时，加载状态应直接完成：

Loaded Count = 0
Total Count = 0
Load Progress = 1.0
Assets Loaded = true

加载事件¶

事件	说明
`OnBuildingAssetLoadProgressChanged`	加载进度或数量发生变化。
`OnBuildingAssetLoaded`	单个建筑资产可以使用。
`OnBuildingAssetsLoaded`	全部建筑资产加载完成。
`OnBuildingAssetLoadingCanceled`	当前异步加载请求被取消。

OnBuildingAssetLoadProgressChanged¶

参数：

参数	类型	说明
`Progress`	`float`	当前加载进度。
`LoadedCount`	`int32`	当前已加载数量。
`TotalCount`	`int32`	本次加载总数量。

可用于更新加载进度条。

OnBuildingAssetLoaded¶

参数：

参数	类型	说明
`BuildingData`	`UBuildingDataAsset*`	本次可用的建筑资产。
`LoadedCount`	`int32`	当前已加载数量。

OnBuildingAssetsLoaded¶

全部建筑资产加载完成后触发。

收到事件后，可以调用 GetAllBuildings() 刷新建造菜单。

使用流程¶

获取 Building Subsystem
→ 检查 Are Building Assets Loaded

已经加载完成：

Get All Buildings
→ 刷新建造菜单

仍在加载：

绑定加载进度事件
→ 更新加载界面

绑定加载完成事件
→ Get All Buildings
→ 刷新建造菜单

成本检测开关¶

UBuildingSubsystem 提供建筑成本检测的运行时开关。

默认状态：

Enable Check Cost = true

GetEnableCheckCost¶

bool GetEnableCheckCost() const;

返回当前是否启用成本检测。

SetEnableCheckCost¶

void SetEnableCheckCost(bool bEnabled);

启用或关闭成本检测。

该值只在当前 GameInstance 生命周期内有效，不会自动写入项目设置或存档。

详细成本流程请参阅建筑成本系统。

资产排序¶

建筑资产加载完成后，按照 SortIndex 从小到大排序：

较小的 SortIndex
→ 显示在前

Subsystem 职责¶

Subsystem	生命周期	负责内容
`UBuildingSubsystem`	`GameInstance`	建筑资产加载、缓存和查询。
`UBuildingWorldSubsystem`	`World`	建筑实体、Chunk、存档和运行时表现。

不要在 UBuildingSubsystem 中保存：

当前世界 Actor
Render Chunk Actor
HISM Component
HISM Instance Index
建筑实体运行时数据

世界建筑管理请参阅 Building World Subsystem。

常见问题¶

问题	检查内容
建筑列表为空	检查资产是否加载完成。
`TotalCount` 为 `0`	检查 Asset Manager 扫描配置。
分类查询为空	检查建筑资产中的 `Category`。
Asset ID 查询失败	检查 Asset ID 和加载状态。
UI 没有刷新	检查是否绑定加载完成事件。
打包后建筑为空	检查 Primary Asset 扫描和打包规则。

建筑资产配置请参阅建筑数据资产。