Building Build Component¶

UBuildingBuildComponent 是本地建造交互的主要入口，负责：

建造模式
建筑预览
建筑选择和编辑
旋转和位置调整
Socket 吸附
成本 UI 评估
默认建造 UI

该组件通常添加到玩家控制的 Pawn 或 Character。

Note

建筑创建、移动和删除应通过 UBuildingBuildComponent 发起。

最终合法性检查和 Entity 修改由服务器执行。

基本信息¶

项目	说明
类名	`UBuildingBuildComponent`
基类	`UActorComponent`
推荐挂载位置	玩家控制的 `Pawn` 或 `Character`
主要用途	本地建造交互和预览控制
蓝图支持	支持
服务器验证	由建筑世界系统负责
默认 UI	可由插件自动创建和管理

基础流程¶

Toggle Build Mode
→ Start Build
→ 调整位置、旋转或吸附点
→ Confirm Build

建造状态¶

EBuildState 表示组件当前的建造状态。

状态	说明
`Idle`	建造模式未启用。
`Ready`	已进入建造模式，但没有活动操作。
`Build`	正在放置新建筑。
`Edit`	正在编辑已有建筑。

常见状态变化：

Idle → Ready
进入建造模式

Ready → Build
开始放置新建筑

Ready → Edit
开始编辑已有建筑

Build / Edit → Ready
完成或取消当前操作

任意活动状态 → Idle
退出建造模式

建造模式接口¶

接口	说明
`ToggleBuildMode`	切换建造模式。
`EnterBuild`	进入建造模式。
`ExitBuild`	完全退出建造模式。
`CancelBuild`	取消当前操作并返回 `Ready`。
`GetCurrentBuildState`	获取当前建造状态。
`IsInBuildMode`	检查是否处于建造模式。
`HasActiveBuildOperation`	检查是否正在放置或编辑建筑。

ToggleBuildMode¶

切换建造模式。

UFUNCTION(BlueprintCallable, Category = "Building|Mode")
void ToggleBuildMode();

当前状态为 Idle 时进入建造模式，否则退出建造模式。

EnterBuild¶

进入建造模式，但不立即放置建筑。

UFUNCTION(BlueprintCallable, Category = "Building|Mode")
void EnterBuild();

调用后状态变为 Ready。

ExitBuild¶

完全退出建造模式。

UFUNCTION(BlueprintCallable, Category = "Building|Mode")
void ExitBuild();

该接口会清理当前预览、选择和编辑状态，并切换到 Idle。

CancelBuild¶

取消当前放置或编辑操作。

UFUNCTION(BlueprintCallable, Category = "Building|Mode")
void CancelBuild();

组件保持在建造模式中，状态返回 Ready。

GetCurrentBuildState¶

获取当前建造状态。

UFUNCTION(BlueprintPure, Category = "Building|Mode")
EBuildState GetCurrentBuildState() const;

类型	数据类型	说明
Return	`EBuildState`	当前建造状态。

IsInBuildMode¶

检查是否已进入建造模式。

UFUNCTION(BlueprintPure, Category = "Building|Mode")
bool IsInBuildMode() const;

类型	数据类型	说明
Return	`bool`	当前状态不是 `Idle` 时返回 `true`。

HasActiveBuildOperation¶

检查是否存在活动建造操作。

UFUNCTION(BlueprintPure, Category = "Building|Mode")
bool HasActiveBuildOperation() const;

类型	数据类型	说明
Return	`bool`	当前状态为 `Build` 或 `Edit` 时返回 `true`。

建造操作接口¶

接口	说明
`StartBuild`	开始放置新建筑。
`RotateBuild`	旋转当前建筑预览。
`AdjustBuildHeight`	调整建筑预览高度。
`AdjustBuildDistance`	调整建筑预览距离。
`ConfirmBuild`	确认当前操作。
`DeleteBuild`	删除当前正在编辑的建筑。
`StartEditBuild`	编辑当前高亮建筑。
`GetCurrentOperationEntityId`	获取当前编辑的 Entity ID。
`GetCurrentBuildingData`	获取当前操作使用的建筑数据。

StartBuild¶

开始放置指定建筑。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void StartBuild(
    UBuildingDataAsset* Data
);

类型	名称	数据类型	说明
Param	`Data`	`UBuildingDataAsset*`	需要放置的建筑数据资产。

调用后，组件创建建筑预览并进入 Build 状态。

RotateBuild¶

旋转当前建筑预览。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void RotateBuild(
    float YawDelta
);

类型	名称	数据类型	说明
Param	`YawDelta`	`float`	本次增加的 Yaw 角度。

例如，每次旋转 90 度：

Yaw Delta = 90

AdjustBuildHeight¶

调整当前建筑预览的高度偏移。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void AdjustBuildHeight(
    float HeightDelta
);

类型	名称	数据类型	说明
Param	`HeightDelta`	`float`	本次增加或减少的高度。

正值向上移动，负值向下移动。

AdjustBuildDistance¶

调整建筑预览与组件 Owner 之间的距离。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void AdjustBuildDistance(
    float InputValue
);

类型	名称	数据类型	说明
Param	`InputValue`	`float`	调整方向，通常使用 `-1` 或 `1`。

实际调整距离为：

Input Value × Build Distance Step

Input Value	结果
`1`	预览向远处移动。
`-1`	预览向近处移动。

Build Distance Step 在插件设置中配置。

ConfirmBuild¶

确认当前操作。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void ConfirmBuild();

行为由当前状态决定：

当前状态	行为
`Build`	提交新建筑放置请求。
`Edit`	提交建筑移动结果。
`Ready`	处理当前建筑选择。

最终位置检查、成本消耗和 Entity 修改由服务器执行。

DeleteBuild¶

删除当前正在编辑的建筑。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void DeleteBuild();

仅在存在有效 Edit 操作时生效。

StartEditBuild¶

开始编辑当前高亮建筑。

UFUNCTION(BlueprintCallable, Category = "Building|Operation")
void StartEditBuild();

成功后进入 Edit 状态，并创建编辑预览。

GetCurrentOperationEntityId¶

获取当前正在编辑的建筑 Entity ID。

UFUNCTION(BlueprintPure, Category = "Building|Operation")
int32 GetCurrentOperationEntityId() const;

类型	数据类型	说明
Return	`int32`	当前 Entity ID；无有效目标时为 `INDEX_NONE`。

GetCurrentBuildingData¶

获取当前操作使用的建筑数据。

UFUNCTION(BlueprintPure, Category = "Building|Operation")
UBuildingDataAsset* GetCurrentBuildingData() const;

类型	数据类型	说明
Return	`UBuildingDataAsset*`	当前建筑数据；无活动操作时可能为 `nullptr`。

建造评估接口¶

EvaluateBuildForUI¶

评估建筑成本和建造要求，用于生成 UI 信息。

UFUNCTION(BlueprintCallable, Category = "Building|Evaluation")
FBuildingBuildCheckResult EvaluateBuildForUI(
    const UBuildingDataAsset* BuildingData,
    const FTransform& PreviewTransform
) const;

类型	名称	数据类型	说明
Param	`BuildingData`	`const UBuildingDataAsset*`	需要评估的建筑数据。
Param	`PreviewTransform`	`const FTransform&`	建筑预览的世界变换。
Return	`CheckResult`	`FBuildingBuildCheckResult`	成本和失败信息。

该接口只用于 UI 评估，不会消耗资源。

Owner 接口¶

GetOwningController¶

获取拥有该组件的 Pawn 对应的 Controller。

UFUNCTION(BlueprintPure, Category = "Building|Owner")
AController* GetOwningController() const;

类型	数据类型	说明
Return	`AController*`	Owner Pawn 的 Controller；失败时返回 `nullptr`。

瞄准接口¶

EBuildingAimMode 决定建筑射线的来源。

模式	说明
`CameraCenter`	从摄像机或屏幕中心发射射线。
`MouseCursor`	从鼠标光标位置发射射线。

SetBuildingAimMode¶

修改当前瞄准模式。

UFUNCTION(BlueprintCallable, Category = "Building|Aim")
void SetBuildingAimMode(
    EBuildingAimMode NewAimMode
);

类型	名称	数据类型	说明
Param	`NewAimMode`	`EBuildingAimMode`	新的瞄准模式。

GetBuildingAimMode¶

获取当前瞄准模式。

UFUNCTION(BlueprintPure, Category = "Building|Aim")
EBuildingAimMode GetBuildingAimMode() const;

类型	数据类型	说明
Return	`EBuildingAimMode`	当前瞄准模式。

默认值在组件初始化时从插件设置读取。

吸附候选接口¶

接口	说明
`SelectNextSnapPoint`	选择下一个吸附候选。
`SelectPreviousSnapPoint`	选择上一个吸附候选。
`GetSnapCandidateCount`	获取当前候选数量。
`GetActiveSnapCandidateIndex`	获取当前候选索引。
`ToggleSnapActive`	启用或禁用 Socket 吸附。
`GetSnapActiveState`	获取当前吸附启用状态。

SelectNextSnapPoint¶

选择下一个兼容吸附候选。

UFUNCTION(BlueprintCallable, Category = "Building|Snap")
bool SelectNextSnapPoint();

类型	数据类型	说明
Return	`bool`	成功选择候选时返回 `true`。

该接口优先使用当前缓存，不会主动执行新的范围搜索。

SelectPreviousSnapPoint¶

选择上一个兼容吸附候选。

UFUNCTION(BlueprintCallable, Category = "Building|Snap")
bool SelectPreviousSnapPoint();

类型	数据类型	说明
Return	`bool`	成功选择候选时返回 `true`。

GetSnapCandidateCount¶

获取当前缓存的吸附候选数量。

UFUNCTION(BlueprintPure, Category = "Building|Snap")
int32 GetSnapCandidateCount() const;

类型	数据类型	说明
Return	`int32`	当前候选数量。

GetActiveSnapCandidateIndex¶

获取当前选中的候选索引。

UFUNCTION(BlueprintPure, Category = "Building|Snap")
int32 GetActiveSnapCandidateIndex() const;

类型	数据类型	说明
Return	`int32`	当前索引；未吸附时为 `INDEX_NONE`。

ToggleSnapActive¶

启用或禁用当前组件的 Socket 吸附。

UFUNCTION(BlueprintCallable, Category = "Building|Snap")
void ToggleSnapActive();

关闭后，建筑预览不会自动应用 Socket 吸附。

再次调用可以重新启用吸附。

GetSnapActiveState¶

获取当前吸附启用状态。

UFUNCTION(BlueprintPure, Category = "Building|Snap")
bool GetSnapActiveState() const;

类型	数据类型	说明
Return	`bool`	吸附已启用时返回 `true`。

吸附配置请参阅吸附系统。

事件¶

事件	说明
`OnBuildingCheck`	Ghost 执行放置合法性检查时触发。
`OnBuildingSelected`	当前选中的建筑数据变化时触发。
`OnBuildStateChanged`	建造状态变化时触发。

OnBuildingCheck¶

建筑预览执行合法性检查时触发。

UPROPERTY(BlueprintAssignable, Category = "Building|Events")
FOnBuildingCheck OnBuildingCheck;

委托定义：

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FOnBuildingCheck,
    FGhostCheckResultContext,
    Context
);

类型	名称	数据类型	说明
Param	`Context`	`FGhostCheckResultContext`	当前 Ghost 检测结果。

该事件可用于更新：

可放置状态提示
失败原因
建筑预览 UI
自定义检测提示

OnBuildingSelected¶

当前选中的建筑数据变化时触发。

UPROPERTY(BlueprintAssignable, Category = "Building|Events")
FOnBuildingSelected OnBuildingSelected;

委托定义：

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(
    FOnBuildingSelected,
    UBuildingDataAsset*,
    Data
);

类型	名称	数据类型	说明
Param	`Data`	`UBuildingDataAsset*`	当前选中的建筑数据。

该事件可用于更新建筑详情、成本信息或选中项 UI。

OnBuildStateChanged¶

建造状态变化时触发。

UPROPERTY(BlueprintAssignable, Category = "Building|Events")
FOnBuildStateChanged OnBuildStateChanged;

委托定义：

DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
    FOnBuildStateChanged,
    EBuildState,
    PreviousState,
    EBuildState,
    NewState
);

类型	名称	数据类型	说明
Param	`PreviousState`	`EBuildState`	变化前状态。
Param	`NewState`	`EBuildState`	变化后状态。

该事件可用于：

显示或隐藏建造 UI
切换输入映射
更新操作提示
判断操作完成或取消

默认 UI¶

当项目设置中的 UI Handling Mode 为 Use Default 时，组件会自动管理默认建造界面。

状态	默认 UI 行为
`Idle`	隐藏建造界面。
`Ready`	显示建筑选择界面。
`Build`	显示建筑放置信息。
`Edit`	显示建筑编辑信息。

项目通常只需要调用：

Toggle Build Mode

使用自定义 UI 时，可以监听：

On Building Check
On Building Selected
On Build State Changed

UI 配置请参阅插件设置。

多人游戏¶

内容	执行位置
输入处理	本地玩家
Ghost Preview	本地玩家
吸附候选计算	本地玩家
成本 UI 评估	本地玩家
建筑请求提交	本地玩家
最终位置验证	服务器
资源消耗	服务器
Entity 创建、移动和删除	服务器
建筑结果同步	插件网络系统

UBuildingBuildComponent 负责本地交互，但不会绕过服务器权威验证。

常见问题¶

问题	检查内容
无法进入建造模式	检查组件是否添加到本地玩家 Pawn。
`StartBuild` 没有创建预览	检查 `Building Data Asset` 和 `Preview Mesh`。
`ConfirmBuild` 没有生成建筑	检查 Ghost 合法性、成本和服务器请求。
无法选择建筑	检查建筑选择碰撞通道。
无法进入编辑状态	检查是否已高亮有效建筑。
旋转没有效果	检查是否存在活动建筑预览。
无法搜索吸附点	检查吸附状态、碰撞通道和 Snap 配置。
无法切换吸附点	检查是否存在多个兼容候选。
默认 UI 没有显示	检查 `UI Handling Mode` 和 `Build Widget Class`。
自定义 UI 没有刷新	检查相关事件是否正确绑定。
客户端操作无响应	检查 Request Actor 和服务器连接。

输入	推荐接口
切换建造模式	`ToggleBuildMode`
确认	`ConfirmBuild`
取消	`CancelBuild`
旋转	`RotateBuild`
调整高度	`AdjustBuildHeight`
调整距离	`AdjustBuildDistance`
下一个吸附点	`SelectNextSnapPoint`
上一个吸附点	`SelectPreviousSnapPoint`
启用或禁用吸附	`ToggleSnapActive`
删除建筑	`DeleteBuild`
开始编辑	`StartEditBuild`

Building Build Component¶

基本信息¶

基础流程¶

建造状态¶

建造模式接口¶

ToggleBuildMode¶

EnterBuild¶

ExitBuild¶

CancelBuild¶

GetCurrentBuildState¶

IsInBuildMode¶

HasActiveBuildOperation¶

建造操作接口¶

StartBuild¶

RotateBuild¶

AdjustBuildHeight¶

AdjustBuildDistance¶

ConfirmBuild¶

DeleteBuild¶

StartEditBuild¶

GetCurrentOperationEntityId¶

GetCurrentBuildingData¶

建造评估接口¶

EvaluateBuildForUI¶

Owner 接口¶

GetOwningController¶

瞄准接口¶

SetBuildingAimMode¶

GetBuildingAimMode¶

吸附候选接口¶

SelectNextSnapPoint¶

SelectPreviousSnapPoint¶

GetSnapCandidateCount¶

GetActiveSnapCandidateIndex¶

ToggleSnapActive¶

GetSnapActiveState¶

事件¶

OnBuildingCheck¶

OnBuildingSelected¶

OnBuildStateChanged¶

默认 UI¶

多人游戏¶

推荐输入映射¶

常见问题¶

相关文档¶