Building Entity Types¶

本页说明建筑实体、所有权和存档重建使用的公共数据类型。

类型关系¶

EBuildingOwnerType
└── FBuildingOwnerId
    └── FBuildingEntity
        └── FUpdateBuildingEntityInfo
            └── FEntitySnapTree

FUpdateBuildingEntityIdInfo
├── EntityId
├── WorldTransform
└── FEntitySnapTree

EBuildingOwnerType¶

EBuildingOwnerType 表示建筑所有者类型。

枚举值	说明
`None`	没有有效所有者。
`Player`	玩家。
`Faction`	阵营或队伍。
`NPC`	NPC。
`System`	游戏系统或其他系统级对象。

FBuildingOwnerId¶

FBuildingOwnerId 使用所有者类型和稳定字符串 ID 表示建筑所有权。

该结构不依赖 Player Controller、Player State、Pawn 或 Actor 实例。

字段¶

字段	类型	默认值	说明
`Type`	`EBuildingOwnerType`	`None`	所有者类型。
`Id`	`FString`	空	所有者的稳定标识。

有效的所有者 ID 必须满足：

Type != None
Id 不为空

成员函数¶

函数	说明
`IsValid`	检查所有者类型和 ID 是否有效。
`IsPlayer`	检查所有者是否为玩家。
`None`	创建空所有者 ID。
`Player`	创建玩家所有者 ID。
`Faction`	创建阵营所有者 ID。
`operator==`	比较两个所有者 ID。

项目通常通过 IBuildingOwnerProvider 提供所有者 ID。

接口说明请参阅项目接口。

Warning

不要使用 Actor 名称、对象地址、临时数组索引或运行时 Controller ID 作为持久化所有者 ID。

FBuildingEntity¶

FBuildingEntity 表示一个已放置建筑的持久化数据。

字段¶

字段	类型	默认值	说明
`EntityId`	`int32`	`INDEX_NONE`	建筑实体的唯一标识。
`ChunkId`	`int32`	`0`	当前运行时所属 Chunk。
`WorldTransform`	`FTransform`	Identity	建筑的世界变换。
`BuildableAssetId`	`FPrimaryAssetId`	无效	建筑配置资产 ID。
`OwnerId`	`FBuildingOwnerId`	`None`	建筑所有者。
`EntityData`	`FBuildingEntityData`	默认值	建筑的持久化状态。

EntityId¶

EntityId 用于：

查询建筑
移动或移除建筑
网络同步
Snap Tree 引用
存档恢复

无效 ID 使用：

INDEX_NONE

RebuildAll 保留已有 EntityId，并将下一个 ID 设置为最大现有 ID 加一。

ChunkId¶

ChunkId 是运行时数据。

世界重建时，Chunk 会根据 WorldTransform 重新创建和分配，因此不应将 ChunkId 用作持久化关系。

WorldTransform¶

WorldTransform 保存：

分量	说明
Location	世界位置。
Rotation	世界旋转。
Scale	世界缩放。

BuildableAssetId¶

BuildableAssetId 指向创建该实体时使用的 UBuildingDataAsset。

恢复建筑时，系统通过该 ID 查找建筑数据资产。

OwnerId¶

OwnerId 可用于：

建筑权限
存档归属
阵营判断
建筑统计
资源返还

EntityData¶

EntityData 保存建筑的附加状态，例如：

Gameplay Tags
Attributes
生命值或耐久度
项目扩展数据

FUpdateBuildingEntityInfo¶

FUpdateBuildingEntityInfo 将完整 Entity 和 Snap Tree 组合在一起。

字段	类型	说明
`Entity`	`FBuildingEntity`	完整建筑实体。
`SnapTree`	`FEntitySnapTree`	建筑吸附关系。

主要用于：

接口	作用
`CollectSaveRecords`	收集当前建筑记录。
`RebuildAll`	根据记录重建建筑世界。

CollectSaveRecords
→ 保存 TArray<FUpdateBuildingEntityInfo>
→ 读取存档
→ RebuildAll

Note

Snap Tree 表示吸附关系，不用于结构支撑判断。

FUpdateBuildingEntityIdInfo¶

FUpdateBuildingEntityIdInfo 是轻量更新结构。

字段	类型	默认值	说明
`EntityId`	`int32`	`INDEX_NONE`	目标实体 ID。
`WorldTransform`	`FTransform`	Identity	更新后的世界变换。
`SnapTree`	`FEntitySnapTree`	默认值	更新后的吸附关系。

该类型用于不需要传递完整 EntityData 的内部更新操作。

普通项目通常不需要自行创建该结构。

类型用途¶

类型	用途	完整 Entity	Snap Tree
`FBuildingOwnerId`	建筑所有者	否	否
`FBuildingEntity`	单个建筑实体	是	否
`FUpdateBuildingEntityInfo`	存档和世界重建	是	是
`FUpdateBuildingEntityIdInfo`	轻量更新	否	是

存档规则¶

应保存	不应保存
`EntityId`	Actor 指针
`WorldTransform`	HISM Component 指针
`BuildableAssetId`	HISM Instance Index
`OwnerId`	Render Chunk Actor 指针
`EntityData`	运行时组件映射
`SnapTree`	客户端预览状态

重建时：

保留 EntityId
→ 根据 WorldTransform 重新分配 Chunk
→ 重建运行时表现
→ Next Entity Id = 最大现有 Entity Id + 1

功能	接口
查询一个实体	`UBuildingWorldSubsystem::TryFindEntity`
获取全部实体	`UBuildingWorldSubsystem::GetAllEntity`
收集存档记录	`UBuildingWorldSubsystem::CollectSaveRecords`
重建建筑世界	`UBuildingWorldSubsystem::RebuildAll`
获取所有者 ID	`IBuildingOwnerProvider::GetBuildingOwnerId`