Building World Subsystem¶

UBuildingWorldSubsystem 是当前世界的建筑运行时子系统，主要提供建筑 Entity 查询、存档数据收集和建筑世界重建接口。

建筑创建、移动和删除应通过 UBuildingBuildComponent 调用。

Note

类中部分函数虽然声明为 public，但仅用于插件内部组件之间的协作，因此不作为推荐 API 公开说明。

基本信息¶

项目	说明
类名	`UBuildingWorldSubsystem`
基类	`UWorldSubsystem`
生命周期	与当前 `UWorld` 相同
主要用途	Entity 查询、存档收集和世界重建
蓝图支持	部分接口支持
多人权限	重建和清除操作应由服务器执行

获取 Subsystem¶

蓝图¶

Get World Subsystem
→ Building World Subsystem

C++¶

// Copyright 2026 Zhiying Li. All Rights Reserved.

UBuildingWorldSubsystem* BuildingWorldSubsystem =
    GetWorld()->GetSubsystem<UBuildingWorldSubsystem>();

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

Entity 查询接口¶

接口	说明
`TryFindEntity`	根据 Entity ID 查询一个建筑 Entity。
`GetAllEntity`	获取当前世界中的所有建筑 Entity。
`CollectSaveRecords`	收集用于存档和重建的建筑记录。

TryFindEntity¶

根据 Entity ID 查询建筑数据。

UFUNCTION(BlueprintCallable, Category = "Building|World|Entity")
bool TryFindEntity(
    int32 EntityId,
    FBuildingEntity& OutEntity
) const;

类型	名称	数据类型	说明
Param	`EntityId`	`int32`	需要查询的建筑 Entity ID。
Param	`OutEntity`	`FBuildingEntity&`	查询成功后写入 Entity 数据。
Return	`bFound`	`bool`	找到对应 Entity 时返回 `true`。

GetAllEntity¶

返回当前已注册 Chunk 中的所有建筑 Entity。

UFUNCTION(BlueprintCallable, Category = "Building|World|Entity")
TArray<FBuildingEntity> GetAllEntity() const;

类型	名称	数据类型	说明
Return	`Entities`	`TArray<FBuildingEntity>`	当前世界中的建筑 Entity 数组。

该接口适合：

调试建筑数据
项目自定义查询
编辑器工具
运行时统计

存档时应优先使用 CollectSaveRecords()。

CollectSaveRecords¶

收集当前建筑世界中的完整存档记录。

UFUNCTION(BlueprintCallable, Category = "Building|World|Entity")
TArray<FUpdateBuildingEntityInfo> CollectSaveRecords() const;

类型	名称	数据类型	说明
Return	`SavedRecords`	`TArray<FUpdateBuildingEntityInfo>`	用于保存和重建建筑世界的数据。

推荐流程：

Collect Save Records
→ 保存到项目存档
→ 加载存档
→ Rebuild All

项目不需要自行保存 HISM Component、Instance Index、Chunk Actor 或建筑 Actor 引用。

详细说明请参阅存档与恢复。

世界管理接口¶

接口	说明
`RebuildAll`	根据存档记录重建整个建筑世界。
`RemoveAll`	清除当前世界中的所有建筑运行时数据。

RebuildAll¶

根据保存的建筑记录重建建筑世界。

UFUNCTION(BlueprintCallable, Category = "Building|World")
void RebuildAll(
    const TArray<FUpdateBuildingEntityInfo>& SavedRecords
);

类型	名称	数据类型	说明
Param	`SavedRecords`	`TArray<FUpdateBuildingEntityInfo>`	由 `CollectSaveRecords()` 收集的建筑记录。
Return	—	`void`	无返回值。

该接口会重新建立：

建筑 Entity
Chunk
HISM Instance
Actor 模式建筑
Entity 与 Chunk 的运行时映射
存档记录中包含的建筑数据

多人游戏中应由服务器调用：

服务器读取存档
→ Rebuild All
→ 插件同步建筑数据
→ 客户端重建建筑表现

Warning

客户端不应自行读取同一份世界存档并调用 RebuildAll()，否则可能产生重复建筑或 Entity ID 冲突。

RemoveAll¶

清除当前世界中的所有建筑运行时数据。

UFUNCTION(BlueprintCallable, Category = "Building|World")
void RemoveAll();

类型	名称	数据类型	说明
Return	—	`void`	无返回值。

该接口会清理建筑 Entity、Chunk Actor 和相关运行时索引。

适合用于：

切换世界存档
重置建筑世界
加载另一份建筑数据前清理当前内容

多人游戏中应由服务器调用。

Entity 事件¶

Entity 事件用于监听建筑网络数据变化。

当前事件使用原生 Multicast Delegate，只能从 C++ 绑定。

事件	参数	触发时机
`OnBuildingNetEntityAdded`	`const FBuildingEntity&`	建筑 Entity 被添加后。
`OnBuildingNetEntityChanged`	`const FBuildingEntity&`	建筑位置或主要数据发生变化后。
`OnBuildingNetEntityRemoved`	`const FBuildingEntity&`	建筑 Entity 被移除后。
`OnBuildingNetEntityDataChange`	`const FBuildingEntity&`	Entity Tags 或 Attributes 发生变化后。

C++ 绑定示例¶

// Copyright 2026 Zhiying Li. All Rights Reserved.

BuildingWorldSubsystem->OnBuildingNetEntityAdded.AddUObject(
    this,
    &UMyComponent::HandleBuildingEntityAdded
);

回调函数：

// Copyright 2026 Zhiying Li. All Rights Reserved.

void UMyComponent::HandleBuildingEntityAdded(
    const FBuildingEntity& Entity
)
{
    // Handle the added building entity.
}

这些事件当前没有使用 BlueprintAssignable，因此不能直接在蓝图中绑定。

未公开说明的接口¶

以下接口主要用于插件内部协作，不建议普通项目直接调用：

类别	示例
建造内部入口	`ConfirmBuild`、`ConfirmMoveBuild`、`ConfirmRemoveBuild`
服务器实现	`ConfirmBuild_ServerOnly`、`ConfirmMoveBuild_ServerOnly`
Chunk 管理	`RegisterChunk`、`UnRegisterChunk`、`GetOrCreateChunkByLocation`
网络回调	`OnNetEntityAdded`、`OnNetEntityChanged`、`OnNetEntityRemoved`
Actor 绑定	`TryBindBuildActorToChunk`、`RegisterPendingBuildActor`
Request Actor	`SetRequestActor`、`ClearRequestActor`、`GetRequestActor`
内部 Snap Tree	`FindSnapTree`、`RemoveSnapTree`

这些接口可能在后续插件版本中随内部实现调整，不应作为项目主要接入点。

与其他 Subsystem 的区别¶

类型	生命周期	负责内容
`UBuildingSubsystem`	`GameInstance`	建筑数据资产加载、缓存和查询。
`UBuildingWorldSubsystem`	`World`	当前世界中的 Entity、Chunk、存档和运行时数据。

简单区分：

类型	管理的问题
`UBuildingSubsystem`	一种建筑如何配置。
`UBuildingWorldSubsystem`	当前世界中实际存在哪些建筑。

建筑资产接口请参阅 Building Subsystem。

多人游戏¶

操作	推荐执行位置
`TryFindEntity`	服务器或客户端本地数据
`GetAllEntity`	服务器或客户端本地数据
`CollectSaveRecords`	服务器
`RebuildAll`	服务器
`RemoveAll`	服务器
Entity 事件监听	服务器或客户端

客户端查询到的是当前客户端已经同步完成的本地建筑数据。

服务器数据应作为最终权威结果。

常见问题¶

问题	检查内容
无法获取 Subsystem	检查当前 `World` 是否有效。
`TryFindEntity` 返回 `false`	检查 Entity ID 是否存在以及所属 Chunk 是否已注册。
`GetAllEntity` 返回空数组	检查当前世界是否已经创建或恢复建筑。
`CollectSaveRecords` 返回空数组	检查是否在正确的世界和服务器调用。
`RebuildAll` 后建筑重复	检查是否重复调用重建接口。
客户端没有显示恢复的建筑	检查是否由服务器调用 `RebuildAll()`。
Entity 事件无法在蓝图绑定	当前事件只支持 C++。
切换关卡后 Subsystem 数据消失	`UWorldSubsystem` 会随当前世界销毁。

操作	推荐入口
进入或退出建造模式	`UBuildingBuildComponent`
开始放置建筑	`UBuildingBuildComponent`
确认建筑	`UBuildingBuildComponent`
编辑或移动建筑	`UBuildingBuildComponent`
删除建筑	`UBuildingBuildComponent`
查询 Entity	`UBuildingWorldSubsystem`
获取全部 Entity	`UBuildingWorldSubsystem`
收集存档记录	`UBuildingWorldSubsystem`
重建建筑世界	`UBuildingWorldSubsystem`
查询建筑数据资产	`UBuildingSubsystem`