Building Cost Types¶

This page describes the public data types used by the building cost system, including cost targets, cost entries, runtime context, execution results, and UI data.

Type Relationships¶

FBuildingCostEntry
└── Costs
    └── FBuildingCostTargetAmount
        └── TargetData
            └── Types derived from FBuildingCostTargetBase

UBuildingCostEvaluator
├── CanAfford
├── Consume
└── EvaluateForUI

UBuildingCostSet
└── CostEntries
    └── FBuildingCostEntry

Cost Target Types¶

A cost target identifies the resource, currency, item, or other object that an Evaluator needs to validate or consume.

All cost target types derive from:

FBuildingCostTargetBase

FBuildingCostTargetBase¶

The base structure for cost targets. It does not contain any data by itself.

USTRUCT(BlueprintType)
struct FBuildingCostTargetBase
{
    GENERATED_BODY()
};

Projects can derive from this structure to create custom cost target types.

Built-in Target Types¶

Type	Field	Data Type	Description
`FBuildingCostTarget_Name`	`Name`	`FName`	Identifies the target by name.
`FBuildingCostTarget_IntId`	`Id`	`int32`	Identifies the target with an integer ID.
`FBuildingCostTarget_GameplayTag`	`Tag`	`FGameplayTag`	Identifies the target with a Gameplay Tag.
`FBuildingCostTarget_PrimaryAssetId`	`AssetId`	`FPrimaryAssetId`	Identifies the target with a Primary Asset ID.
`FBuildingCostTarget_SoftObject`	`Asset`	`TSoftObjectPtr<UObject>`	Identifies the target with a soft object reference.

FBuildingCostTarget_Name¶

USTRUCT(BlueprintType)
struct FBuildingCostTarget_Name
    : public FBuildingCostTargetBase
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    FName Name = NAME_None;
};

Suitable for projects that use resource names or other project-defined names as identifiers.

FBuildingCostTarget_IntId¶

USTRUCT(BlueprintType)
struct FBuildingCostTarget_IntId
    : public FBuildingCostTargetBase
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    int32 Id = INDEX_NONE;
};

Suitable for projects that use database IDs, item IDs, or resource numbers.

FBuildingCostTarget_GameplayTag¶

USTRUCT(BlueprintType)
struct FBuildingCostTarget_GameplayTag
    : public FBuildingCostTargetBase
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    FGameplayTag Tag;
};

For example:

Resource.Wood
Resource.Stone
Currency.Gold

FBuildingCostTarget_PrimaryAssetId¶

USTRUCT(BlueprintType)
struct FBuildingCostTarget_PrimaryAssetId
    : public FBuildingCostTargetBase
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    FPrimaryAssetId AssetId;
};

Suitable for projects that manage items or resources through Unreal Engine's Primary Asset system.

FBuildingCostTarget_SoftObject¶

USTRUCT(BlueprintType)
struct FBuildingCostTarget_SoftObject
    : public FBuildingCostTargetBase
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    TSoftObjectPtr<UObject> Asset;
};

A soft reference does not guarantee that the target asset has already been loaded. The Evaluator should handle loading according to project requirements.

FBuildingCostTargetAmount¶

FBuildingCostTargetAmount represents a cost target and its required amount.

USTRUCT(BlueprintType)
struct FBuildingCostTargetAmount
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    bool bEnabled = true;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    TInstancedStruct<FBuildingCostTargetBase> TargetData;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost",
        meta = (ClampMin = "0")
    )
    int32 Amount = 1;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost|UI"
    )
    FText DisplayName;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost|UI"
    )
    TObjectPtr<UTexture2D> Icon = nullptr;
};

Field	Data Type	Default	Description
`bEnabled`	`bool`	`true`	Determines whether the current cost target is enabled.
`TargetData`	`TInstancedStruct<FBuildingCostTargetBase>`	Empty	The concrete data of the current target.
`Amount`	`int32`	`1`	The amount to validate or consume.
`DisplayName`	`FText`	Empty	Optional UI display-name override.
`Icon`	`UTexture2D*`	`nullptr`	Optional UI icon override.

TargetData can only use structures derived from FBuildingCostTargetBase.

For example:

Target Data Type	Example
`FBuildingCostTarget_GameplayTag`	`Resource.Wood`
`FBuildingCostTarget_IntId`	`1001`
`FBuildingCostTarget_Name`	`Wood`
`FBuildingCostTarget_PrimaryAssetId`	`Item:DA_Wood`
`FBuildingCostTarget_SoftObject`	Item data asset

DisplayName and Icon are used only as UI overrides. When they are not configured, the Evaluator can obtain display information from the target data or the project's resource system.

FBuildingCostEntry¶

FBuildingCostEntry represents a group of cost targets processed by the same Evaluator.

USTRUCT(BlueprintType)
struct FBuildingCostEntry
{
    GENERATED_BODY()

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    bool bEnabled = true;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    FGameplayTag CostTypeTag;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    TSubclassOf<UBuildingCostEvaluator> EvaluatorClass;

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    TArray<FBuildingCostTargetAmount> Costs;
};

Field	Data Type	Default	Description
`bEnabled`	`bool`	`true`	Determines whether the current cost entry is enabled.
`CostTypeTag`	`FGameplayTag`	Empty	The cost type of the current entry.
`EvaluatorClass`	`TSubclassOf<UBuildingCostEvaluator>`	Empty	Optional Evaluator override.
`Costs`	`TArray<FBuildingCostTargetAmount>`	Empty	The list of targets processed by the current Evaluator.

CostTypeTag¶

CostTypeTag identifies the cost type, for example:

Cost.Resource
Cost.Currency
Cost.Item
Cost.Reputation
Cost.BuildingPoint

When EvaluatorClass is not configured, the system uses CostTypeTag to find an Evaluator from Default Evaluators in the project settings.

Default Evaluators use exact Gameplay Tag matching. Parent and child Tags are not matched automatically.

EvaluatorClass¶

Configuration	Evaluator Used
Configured	Uses the `EvaluatorClass` specified by the current Entry.
Not configured	Finds the project-default Evaluator using `CostTypeTag`.

Costs¶

A single Entry can contain multiple targets processed by the same Evaluator.

For example:

Target	Amount
`Resource.Wood`	`10`
`Resource.Stone`	`5`

FBuildingCostContext¶

FBuildingCostContext provides the runtime context required for cost validation and resource consumption.

Evaluators should obtain the required objects from the Context and should not retain these references long-term.

USTRUCT(BlueprintType)
struct FBuildingCostContext
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    TObjectPtr<UObject> WorldContextObject = nullptr;

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    TObjectPtr<AController> Controller = nullptr;

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    TObjectPtr<UBuildingBuildComponent>
        BuildingBuildComponent = nullptr;

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    TObjectPtr<const UBuildingDataAsset>
        BuildingData = nullptr;

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    FTransform BuildTransform = FTransform::Identity;
};

Field	Data Type	Default	Description
`WorldContextObject`	`UObject*`	`nullptr`	Used to obtain the current `UWorld`.
`Controller`	`AController*`	`nullptr`	The Controller associated with the current building operation.
`BuildingBuildComponent`	`UBuildingBuildComponent*`	`nullptr`	The component that initiated the current building operation.
`BuildingData`	`const UBuildingDataAsset*`	`nullptr`	The current building data asset.
`BuildTransform`	`FTransform`	Identity	The world transform requested for the current building operation.

WorldContextObject¶

Used to resolve the current world:

UWorld* World =
    IsValid(Context.WorldContextObject)
    ? Context.WorldContextObject->GetWorld()
    : nullptr;

Controller¶

Represents the initiator of the current building operation.

An Evaluator can use it to obtain:

Pawn
Player State
Inventory Component
Currency Component
Project permission data

The field type is AController*, so it can also contain an AI Controller.

BuildingBuildComponent¶

Represents the building component that initiated the current operation.

Projects can use it to obtain:

Component Owner
Pawn
Inventory or resource components
Faction or settlement data
Project-specific cost sources

BuildingData¶

Represents the building configuration currently being evaluated.

An Evaluator can read the building type, Gameplay Tags, Cost Set, and project-specific configuration from it.

This object is read-only and should not be modified during cost evaluation.

BuildTransform¶

Represents the world transform requested for the current building operation.

It can be used to implement location-dependent costs or requirements, such as:

Calculating costs according to the region
Increasing costs based on building height
Checking territory or location permissions
Calculating resource consumption based on distance

Standard resource costs can ignore this field.

Validity Checks¶

An Evaluator should not assume that every object in the Context is always valid.

if (!IsValid(Context.Controller))
{
    return FBuildingCostResult::Failure(
        NSLOCTEXT(
            "BuildingCost",
            "InvalidController",
            "Unable to resolve the building owner."
        )
    );
}

The fields that need to be checked depend on the Evaluator implementation.

FBuildingCostResult¶

FBuildingCostResult represents the result of a cost check or resource consumption operation.

USTRUCT(BlueprintType)
struct FBuildingCostResult
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    bool bSuccess = true;

    UPROPERTY(BlueprintReadOnly, Category = "Building|Cost")
    FText FailReason;
};

Field	Data Type	Default	Description
`bSuccess`	`bool`	`true`	Whether the operation succeeded.
`FailReason`	`FText`	Empty	The reason for failure when the operation does not succeed.

Success¶

Creates a successful result.

static FBuildingCostResult Success();

Failure¶

Creates a failed result.

static FBuildingCostResult Failure(
    const FText& Reason
);

Type	Name	Data Type	Description
Param	`Reason`	`const FText&`	The failure reason.
Return	`Result`	`FBuildingCostResult`	The failed result.

These helper functions are primarily intended for C++ usage.

FBuildingCostLine¶

FBuildingCostLine represents one resource, currency, or item cost row in the building UI.

USTRUCT(BlueprintType)
struct FBuildingCostLine
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FText DisplayName;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    TObjectPtr<UTexture2D> Icon = nullptr;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    int32 RequiredAmount = 0;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    int32 OwnedAmount = 0;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    bool bEnough = true;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FGameplayTag CostTypeTag;
};

Field	Data Type	Default	Description
`DisplayName`	`FText`	Empty	The cost name.
`Icon`	`UTexture2D*`	`nullptr`	The cost icon.
`RequiredAmount`	`int32`	`0`	The required amount.
`OwnedAmount`	`int32`	`0`	The currently owned amount.
`bEnough`	`bool`	`true`	Whether the current amount is sufficient.
`CostTypeTag`	`FGameplayTag`	Empty	The current cost type.

FBuildingRequirementLine¶

FBuildingRequirementLine represents a non-resource building requirement.

Common uses include:

Player level
Technology unlocks
Building permissions
Reputation requirements
Project-specific restrictions

USTRUCT(BlueprintType)
struct FBuildingRequirementLine
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FText DisplayName;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FText CurrentValueText;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FText RequiredValueText;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    bool bPassed = true;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FText FailReason;
};

Field	Data Type	Default	Description
`DisplayName`	`FText`	Empty	The requirement name.
`CurrentValueText`	`FText`	Empty	The current state or value.
`RequiredValueText`	`FText`	Empty	The required state or value.
`bPassed`	`bool`	`true`	Whether the current requirement is satisfied.
`FailReason`	`FText`	Empty	The reason when the requirement is not satisfied.

FBuildingBuildCheckResult¶

FBuildingBuildCheckResult is the aggregated UI result for all costs and requirements.

USTRUCT(BlueprintType)
struct FBuildingBuildCheckResult
{
    GENERATED_BODY()

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    bool bCanBuild = true;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    TArray<FBuildingCostLine> CostLines;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    TArray<FBuildingRequirementLine> RequirementLines;

    UPROPERTY(BlueprintReadWrite, Category = "Building|UI")
    FText FirstFailReason;
};

Field	Data Type	Default	Description
`bCanBuild`	`bool`	`true`	Whether all costs and requirements are satisfied.
`CostLines`	`TArray<FBuildingCostLine>`	Empty	Cost data used by the UI.
`RequirementLines`	`TArray<FBuildingRequirementLine>`	Empty	Non-resource requirement data used by the UI.
`FirstFailReason`	`FText`	Empty	The first failure reason.

This result can be generated by:

UBuildingCostEvaluator::EvaluateForUI

or:

UBuildingBuildComponent::EvaluateBuildForUI

UBuildingCostEvaluator¶

UBuildingCostEvaluator is the base class for cost processors.

Projects can derive from this class in Blueprint or C++ to integrate their own inventory, currency, or resource systems.

API	Description
`CanAfford`	Checks whether the current cost can be paid.
`Consume`	Consumes the current cost.
`EvaluateForUI`	Generates cost and requirement information for the UI.

CanAfford¶

UFUNCTION(
    BlueprintNativeEvent,
    BlueprintCallable,
    Category = "Building|Cost"
)
FBuildingCostResult CanAfford(
    const FBuildingCostContext& Context,
    const FBuildingCostEntry& Entry
) const;

This API performs validation only and should not modify resource state.

Consume¶

UFUNCTION(
    BlueprintNativeEvent,
    BlueprintCallable,
    Category = "Building|Cost"
)
FBuildingCostResult Consume(
    const FBuildingCostContext& Context,
    const FBuildingCostEntry& Entry
) const;

This API performs the actual resource consumption.

The implementation should check the available amount again before modifying resources, because runtime data may have changed.

EvaluateForUI¶

UFUNCTION(
    BlueprintNativeEvent,
    BlueprintCallable,
    Category = "Building|Cost"
)
FBuildingBuildCheckResult EvaluateForUI(
    const FBuildingCostContext& Context,
    const FBuildingCostEntry& Entry
) const;

This API generates UI data and should not consume or modify resources.

UBuildingCostSet¶

UBuildingCostSet is the cost configuration asset used by a building.

UCLASS(BlueprintType)
class UBuildingCostSet : public UDataAsset
{
    GENERATED_BODY()

public:

    UPROPERTY(
        EditAnywhere,
        BlueprintReadOnly,
        Category = "Building|Cost"
    )
    TArray<FBuildingCostEntry> CostEntries;
};

CostEntries¶

CostEntries stores the cost entries that a building needs to validate and consume.

A single Cost Set can contain multiple cost types:

Cost.Resource
Cost.Currency
Cost.Item

CanAfford¶

FBuildingCostResult CanAfford(
    const FBuildingCostContext& Context
) const;

Checks all enabled cost entries without consuming resources.

Consume¶

FBuildingCostResult Consume(
    const FBuildingCostContext& Context
) const;

Calls the Evaluator of each cost entry to consume resources.

EvaluateForUI¶

void EvaluateForUI(
    const FBuildingCostContext& Context,
    FBuildingBuildCheckResult& InOutResult
) const;

Appends UI data from each cost entry to the existing check result.

UI Usage Recommendations¶

Data	Usage
`bCanBuild`	Controls whether the confirmation button is enabled.
`CostLines`	Displays resource, currency, or item costs.
`RequirementLines`	Displays level, permission, and other requirements.
`FirstFailReason`	Displays a short failure message.
`bEnough`	Indicates whether an individual cost is satisfied.
`bPassed`	Indicates whether an individual requirement is satisfied.

Type Usage¶

Type	Primary Purpose
`FBuildingCostTargetBase`	Base structure for custom cost targets.
`FBuildingCostTargetAmount`	A single target and amount.
`FBuildingCostEntry`	A group of costs processed by the same Evaluator.
`FBuildingCostContext`	Runtime context for cost operations.
`FBuildingCostResult`	Validation or consumption result.
`FBuildingCostLine`	UI cost row.
`FBuildingRequirementLine`	UI requirement row.
`FBuildingBuildCheckResult`	Complete UI evaluation result.
`UBuildingCostEvaluator`	Project-defined cost processor.
`UBuildingCostSet`	Building cost configuration asset.

Building Cost Types¶

Type Relationships¶

Cost Target Types¶

FBuildingCostTargetBase¶

Built-in Target Types¶

FBuildingCostTarget_Name¶

FBuildingCostTarget_IntId¶

FBuildingCostTarget_GameplayTag¶

FBuildingCostTarget_PrimaryAssetId¶

FBuildingCostTarget_SoftObject¶

FBuildingCostTargetAmount¶

FBuildingCostEntry¶

CostTypeTag¶

EvaluatorClass¶

Costs¶

FBuildingCostContext¶

WorldContextObject¶

Controller¶

BuildingBuildComponent¶

BuildingData¶

BuildTransform¶

Validity Checks¶

FBuildingCostResult¶

Success¶

Failure¶

FBuildingCostLine¶

FBuildingRequirementLine¶

FBuildingBuildCheckResult¶

UBuildingCostEvaluator¶

CanAfford¶

Consume¶

EvaluateForUI¶

UBuildingCostSet¶

CostEntries¶

CanAfford¶

Consume¶

EvaluateForUI¶

UI Usage Recommendations¶

Type Usage¶

Related Documentation¶