Building Utils

UBuildingUtils 是 Modular Building System 提供的蓝图函数库，用于获取建筑 Subsystem、查询建筑 Entity、处理 HISM Socket、创建成本结果以及查找建造组件。

基本信息

项目	说明
类名	UBuildingUtils
基类	UBlueprintFunctionLibrary
主要用途	提供常用建筑辅助函数
蓝图支持	支持
实例化	不需要创建实例

Subsystem 获取接口

接口	说明
GetBuildingSystem	获取当前 GameInstance 的建筑资产 Subsystem。
GetBuildingSubSystem	获取当前世界的建筑运行时 Subsystem。

GetBuildingSystem

获取指定世界对应的 UBuildingSubsystem。

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(BlueprintCallable, Category = "Building")
static UBuildingSubsystem* GetBuildingSystem(
    UWorld* World
);

类型	名称	数据类型	说明
Param	World	UWorld*	用于获取 GameInstance 和建筑 Subsystem 的世界。
Return	BuildingSystem	UBuildingSubsystem*	获取成功时返回建筑资产 Subsystem，否则返回 nullptr。

该 Subsystem 负责：

功能	说明
建筑资产加载	加载项目中的 UBuildingDataAsset。
建筑列表查询	获取全部建筑或指定分类中的建筑。
Asset ID 查询	根据 FPrimaryAssetId 查询建筑数据。

GetBuildingSubSystem

获取指定世界对应的 UBuildingWorldSubsystem。

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(BlueprintCallable, Category = "Building")
static UBuildingWorldSubsystem* GetBuildingSubSystem(
    UWorld* World
);

类型	名称	数据类型	说明
Param	World	UWorld*	用于获取建筑世界 Subsystem 的世界。
Return	BuildingWorldSubsystem	UBuildingWorldSubsystem*	获取成功时返回建筑世界 Subsystem，否则返回 nullptr。

该 Subsystem 主要负责：

功能	说明
Entity 查询	查询当前世界中的建筑 Entity。
存档收集	收集当前建筑世界的存档记录。
世界重建	根据存档数据恢复建筑世界。

Entity 查询接口

接口	说明
GetEntityId	从碰撞命中对象中解析 Entity ID。
TryGetEntity	从碰撞命中对象中解析完整的建筑 Entity。

GetEntityId

根据碰撞命中的 Actor、组件和 Instance Index 获取建筑 Entity ID。

该接口同时支持 Actor 渲染模式和 HISM 渲染模式。

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(BlueprintCallable, Category = "Building|Entity")
static int32 GetEntityId(
    AActor* HitActor,
    UPrimitiveComponent* HitComp,
    int32 ItemIndex
);

类型	名称	数据类型	说明
Param	HitActor	AActor*	碰撞查询命中的 Actor。
Param	HitComp	UPrimitiveComponent*	碰撞查询命中的组件。
Param	ItemIndex	int32	命中的 ISM 或 HISM Instance Index。
Return	EntityId	int32	找到时返回 Entity ID，否则返回 INDEX_NONE。

常见输入来源：

Line Trace / Hit Result
├── Hit Actor
├── Hit Component
└── Hit Item

建筑渲染模式	Entity ID 来源
Actor	从建筑 Actor 中解析。
HISM	根据命中组件和 Instance Index 查询。

TryGetEntity

根据碰撞命中信息查询完整的 FBuildingEntity。

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(BlueprintCallable, Category = "Building|Entity")
static bool TryGetEntity(
    UWorld* World,
    FBuildingEntity& Entity,
    AActor* HitActor,
    UPrimitiveComponent* HitComp,
    int32 ItemIndex
);

类型	名称	数据类型	说明
Param	World	UWorld*	建筑 Entity 所属的世界。
Param	Entity	FBuildingEntity&	查询成功后写入完整的 Entity 数据。
Param	HitActor	AActor*	碰撞查询命中的 Actor。
Param	HitComp	UPrimitiveComponent*	碰撞查询命中的组件。
Param	ItemIndex	int32	命中的 ISM 或 HISM Instance Index。
Return	bFound	bool	成功解析并找到 Entity 时返回 true。

该接口相当于执行：

碰撞命中信息
→ Get Entity ID
→ Building World Subsystem
→ Try Find Entity

需要安全获取完整 Entity 数据时，应优先使用 TryGetEntity，而不是只使用 GetEntityId。

成本结果接口

接口	说明
MakeBuildingCostSuccess	创建成功的成本结果。
MakeBuildingCostFailure	创建包含失败原因的成本结果。

这些接口主要用于蓝图 UBuildingCostEvaluator 实现。

MakeBuildingCostSuccess

创建一个成功的 FBuildingCostResult。

蓝图显示名称：

Building Cost Success

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(
    BlueprintPure,
    Category = "Building|Cost",
    meta = (DisplayName = "Building Cost Success")
)
static FBuildingCostResult MakeBuildingCostSuccess();

类型	名称	数据类型	说明
Return	Result	FBuildingCostResult	bSuccess 为 true 的成本结果。

该接口适用于：

Evaluator 接口	使用场景
CanAfford	玩家拥有足够资源。
Consume	资源已经成功消耗。

MakeBuildingCostFailure

创建一个失败的 FBuildingCostResult。

蓝图显示名称：

Building Cost Failure

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(
    BlueprintPure,
    Category = "Building|Cost",
    meta = (DisplayName = "Building Cost Failure")
)
static FBuildingCostResult MakeBuildingCostFailure(
    const FText& Reason
);

类型	名称	数据类型	说明
Param	Reason	const FText&	面向用户显示的失败原因。
Return	Result	FBuildingCostResult	bSuccess 为 false 并包含失败原因的成本结果。

成本 Evaluator 说明请参阅 Building Cost Evaluator。

Building Build Component 查询接口

接口	说明
FindBuildComponent	从指定 Pawn 上查找建造组件。
FindBuildComponentWithPC	从 Player Controller 当前控制的 Pawn 上查找建造组件。

FindBuildComponent

从指定 Pawn 上查找 UBuildingBuildComponent。

蓝图显示名称：

Find Building Build Component

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(
    BlueprintPure,
    Category = "Building|Component",
    meta = (DisplayName = "Find Building Build Component")
)
static UBuildingBuildComponent* FindBuildComponent(
    const APawn* Pawn
);

类型	名称	数据类型	说明
Param	Pawn	const APawn*	需要查找建造组件的 Pawn。
Return	BuildComponent	UBuildingBuildComponent*	找到时返回建造组件，否则返回 nullptr。

该接口只在指定 Pawn 上搜索组件，不会搜索 Player State、Controller 或其他 Actor。

FindBuildComponentWithPC

从指定 Player Controller 当前控制的 Pawn 上查找 UBuildingBuildComponent。

蓝图显示名称：

Find Building Build Component From Player Controller

// Copyright 2026 Zhiying Li. All Rights Reserved.

UFUNCTION(
    BlueprintPure,
    Category = "Building|Component",
    meta = (
        DisplayName =
        "Find Building Build Component From Player Controller"
    )
)
static UBuildingBuildComponent* FindBuildComponentWithPC(
    const APlayerController* PlayerController
);

类型	名称	数据类型	说明
Param	PlayerController	const APlayerController*	需要查询当前 Pawn 的 Player Controller。
Return	BuildComponent	UBuildingBuildComponent*	Pawn 上存在建造组件时返回该组件，否则返回 nullptr。

该接口适用于 UI、Player Controller 和其他没有直接 Pawn 引用的对象。

接口选择

需求	推荐接口
获取建筑资产 Subsystem	GetBuildingSystem
获取建筑世界 Subsystem	GetBuildingSubSystem
获取 HISM Instance 上的 Socket Transform	GetSocketWorldTransformFixed
判断 Snap Group 是否兼容	HasCommonGroup
判断坐标点是否位于组件包围盒	IsPointInComponentBox
从 Hit Result 获取 Entity ID	GetEntityId
从 Hit Result 获取完整 Entity	TryGetEntity
在蓝图中创建成功成本结果	MakeBuildingCostSuccess
在蓝图中创建失败成本结果	MakeBuildingCostFailure
从 Pawn 获取建造组件	FindBuildComponent
从 Player Controller 获取建造组件	FindBuildComponentWithPC

常见问题

问题	检查内容
Subsystem 返回 nullptr	检查传入的 World 是否有效。
Socket Transform 位置错误	检查 HISM 的 ItemIndex 是否正确。
普通组件 Socket 查询失败	普通组件应传入 INDEX_NONE。
HasCommonGroup 返回 false	检查两个 Snap Point 是否配置了相同分组。
GetEntityId 返回 INDEX_NONE	检查命中的 Actor、组件和 Instance Index。
TryGetEntity 返回 false	检查 Entity 是否已同步以及所属 Chunk 是否已注册。
无法找到建造组件	检查组件是否添加到当前 Pawn。
成本失败结果没有提示	检查传入的 Reason 是否为空。

相关页面：

• Building Subsystem
• Building World Subsystem
• Building Build Component
• Building Entity Types
• Building Cost Types
• Building Cost Evaluator
• 吸附系统