Building Utils¶

UBuildingUtils is a Blueprint Function Library provided by Modular Building System. It contains helper functions for accessing building Subsystems, querying Building Entities, working with HISM Sockets, creating cost results, and locating building components.

Basic Information¶

Item	Description
Class	`UBuildingUtils`
Base Class	`UBlueprintFunctionLibrary`
Primary Purpose	Provides commonly used building helper functions
Blueprint Support	Supported
Instantiation	No instance is required

Subsystem Access APIs¶

API	Description
`GetBuildingSystem`	Gets the building asset Subsystem for the current `GameInstance`.
`GetBuildingSubSystem`	Gets the building runtime Subsystem for the current world.

GetBuildingSystem¶

Gets the UBuildingSubsystem associated with the specified world.

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

Type	Name	Data Type	Description
Param	`World`	`UWorld*`	The world used to access the `GameInstance` and building Subsystem.
Return	`BuildingSystem`	`UBuildingSubsystem*`	Returns the building asset Subsystem on success, or `nullptr` otherwise.

This Subsystem is responsible for:

Functionality	Description
Building asset loading	Loads the project's `UBuildingDataAsset` assets.
Building list queries	Returns all buildings or buildings in a specified category.
Asset ID queries	Queries building data using an `FPrimaryAssetId`.

GetBuildingSubSystem¶

Gets the UBuildingWorldSubsystem associated with the specified world.

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

Type	Name	Data Type	Description
Param	`World`	`UWorld*`	The world used to access the building world Subsystem.
Return	`BuildingWorldSubsystem`	`UBuildingWorldSubsystem*`	Returns the building world Subsystem on success, or `nullptr` otherwise.

This Subsystem is primarily responsible for:

Functionality	Description
Entity queries	Queries Building Entities in the current world.
Save-data collection	Collects save records from the current building world.
World reconstruction	Restores the building world from saved data.

Entity Query APIs¶

API	Description
`GetEntityId`	Resolves an Entity ID from a collision hit.
`TryGetEntity`	Resolves a complete Building Entity from a collision hit.

GetEntityId¶

Gets a Building Entity ID from a hit Actor, component, and Instance Index.

This API supports both Actor and HISM rendering modes.

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

Type	Name	Data Type	Description
Param	`HitActor`	`AActor*`	The Actor hit by the collision query.
Param	`HitComp`	`UPrimitiveComponent*`	The component hit by the collision query.
Param	`ItemIndex`	`int32`	The hit ISM or HISM Instance Index.
Return	`EntityId`	`int32`	Returns the Entity ID when found, or `INDEX_NONE` otherwise.

Common input source:

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

Building Rendering Mode	Entity ID Source
Actor	Resolved from the building Actor.
HISM	Queried using the hit component and Instance Index.

TryGetEntity¶

Queries a complete FBuildingEntity from collision hit information.

// 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
);

Type	Name	Data Type	Description
Param	`World`	`UWorld*`	The world containing the Building Entity.
Param	`Entity`	`FBuildingEntity&`	Receives the complete Entity data when the query succeeds.
Param	`HitActor`	`AActor*`	The Actor hit by the collision query.
Param	`HitComp`	`UPrimitiveComponent*`	The component hit by the collision query.
Param	`ItemIndex`	`int32`	The hit ISM or HISM Instance Index.
Return	`bFound`	`bool`	Returns `true` when the Entity is successfully resolved and found.

This API is equivalent to:

Collision hit information
→ Get Entity ID
→ Building World Subsystem
→ Try Find Entity

When complete Entity data is required, prefer TryGetEntity instead of using only GetEntityId.

Cost Result APIs¶

API	Description
`MakeBuildingCostSuccess`	Creates a successful cost result.
`MakeBuildingCostFailure`	Creates a failed cost result containing a failure reason.

These APIs are primarily intended for Blueprint implementations of UBuildingCostEvaluator.

MakeBuildingCostSuccess¶

Creates a successful FBuildingCostResult.

Blueprint display name:

Building Cost Success

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

Type	Name	Data Type	Description
Return	`Result`	`FBuildingCostResult`	A cost result with `bSuccess` set to `true`.

This API can be used in:

Evaluator API	Usage
`CanAfford`	The player has sufficient resources.
`Consume`	The resources were consumed successfully.

MakeBuildingCostFailure¶

Creates a failed FBuildingCostResult.

Blueprint display name:

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
);

Type	Name	Data Type	Description
Param	`Reason`	`const FText&`	The user-facing failure reason.
Return	`Result`	`FBuildingCostResult`	A cost result with `bSuccess` set to `false` and the specified failure reason.

For more information about cost Evaluators, see Building Cost Evaluator.

Building Build Component Query APIs¶

API	Description
`FindBuildComponent`	Finds the building component on the specified Pawn.
`FindBuildComponentWithPC`	Finds the building component on the Pawn currently controlled by a Player Controller.

FindBuildComponent¶

Finds a UBuildingBuildComponent on the specified Pawn.

Blueprint display name:

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
);

Type	Name	Data Type	Description
Param	`Pawn`	`const APawn*`	The Pawn on which to search for the building component.
Return	`BuildComponent`	`UBuildingBuildComponent*`	Returns the building component when found, or `nullptr` otherwise.

This API searches only the specified Pawn. It does not search the Player State, Controller, or other Actors.

FindBuildComponentWithPC¶

Finds a UBuildingBuildComponent on the Pawn currently controlled by the specified Player Controller.

Blueprint display name:

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
);

Type	Name	Data Type	Description
Param	`PlayerController`	`const APlayerController*`	The Player Controller whose current Pawn should be queried.
Return	`BuildComponent`	`UBuildingBuildComponent*`	Returns the building component on the Pawn, or `nullptr` otherwise.

This API is useful for UI, Player Controllers, and other objects that do not have a direct Pawn reference.

Choosing an API¶

Requirement	Recommended API
Get the building asset Subsystem	`GetBuildingSystem`
Get the building world Subsystem	`GetBuildingSubSystem`
Get a Socket Transform from an HISM Instance	`GetSocketWorldTransformFixed`
Check whether two Snap Groups are compatible	`HasCommonGroup`
Check whether a point is inside a component's bounding box	`IsPointInComponentBox`
Get an Entity ID from a Hit Result	`GetEntityId`
Get a complete Entity from a Hit Result	`TryGetEntity`
Create a successful cost result in Blueprint	`MakeBuildingCostSuccess`
Create a failed cost result in Blueprint	`MakeBuildingCostFailure`
Get the building component from a Pawn	`FindBuildComponent`
Get the building component from a Player Controller	`FindBuildComponentWithPC`

Troubleshooting¶

Issue	What to Check
A Subsystem returns `nullptr`	Check whether the supplied `World` is valid.
The Socket Transform is incorrect	Check whether the HISM `ItemIndex` is correct.
A Socket query fails for a standard component	Pass `INDEX_NONE` for a non-instanced component.
`HasCommonGroup` returns `false`	Check whether both Snap Points have at least one matching Group.
`GetEntityId` returns `INDEX_NONE`	Check the hit Actor, component, and Instance Index.
`TryGetEntity` returns `false`	Check whether the Entity has been synchronized and whether its Chunk is registered.
The building component cannot be found	Check whether the component has been added to the current Pawn.
A failed cost result has no message	Check whether the supplied `Reason` is empty.

Related pages: