跳转至

建筑实体

建筑实体是插件用于表示已放置建筑的核心数据。

每个建筑对应一个 FBuildingEntity，保存建筑标识、世界变换、建筑资产、所有者和持久化状态。

HISM Instance 和 Building Actor 只是根据实体创建的运行时表现。

Note

FBuildingEntity 是建筑的逻辑数据。 Actor 引用、HISM Component 和 Instance Index 不应作为建筑的稳定标识。

数据结构

字段 说明
Entity Id 建筑实体的唯一标识。
Chunk Id 建筑当前所属的运行时 Chunk。
World Transform 建筑的世界位置、旋转和缩放。
Buildable Asset Id 建筑使用的 Building Data Asset。
Owner Id 建筑所属的玩家、阵营、NPC 或系统。
Entity Data 建筑的附加持久化状态。

Entity Id

Entity Id 用于查询、移动、修改和移除建筑。

存档重建时，插件会保留已有建筑的 Entity Id，并将下一个 ID 设置为：

最大现有 Entity Id + 1

Chunk Id

Chunk Id 用于运行时空间分区、渲染和网络管理。

Chunk 会在重建时根据 World Transform 重新分配，因此不应作为长期稳定标识。

详情请参阅 Chunk 系统。

World Transform

World Transform 保存建筑的完整世界变换：

  • Location
  • Rotation
  • Scale

插件使用该变换重新创建 HISM Instance、Building Actor 和碰撞表现。

Buildable Asset Id

Buildable Asset Id 是建筑定义资产的 Primary Asset Id。

插件通过它查找对应的 Building Data Asset，并读取：

  • 渲染模式
  • Static Mesh
  • Actor Class
  • Preview Mesh
  • 其他建筑配置

详情请参阅 建筑数据资产。

Owner Id

Owner Id 由所有者类型和稳定字符串 ID 组成。

字段 说明
Type 所有者类型。
Id 所有者的稳定标识。

支持以下类型：

类型 说明
None 没有有效所有者。
Player 玩家。
Faction 阵营或队伍。
NPC NPC。
System 游戏系统或世界。

Owner Id 不保存 Player Controller、Player State、Pawn 或 Actor 引用。

项目应提供可跨重连和存档保持稳定的 ID。玩家所有者通常通过 Building Owner Provider 接口提供。

Entity Data

Entity Data 保存单个建筑的持久化状态，例如：

  • 建筑生命值
  • Gameplay Tags
  • 自定义属性
  • 项目扩展数据

Note

建筑类型的静态配置应保存在 Building Data Asset。 单个已放置建筑的状态应保存在 Entity Data.

实体与运行时表现

Entity Id
→ Chunk
→ HISM Component 或 Building Actor
→ Instance Index

只有 Entity Id 是稳定的建筑标识。

Instance Index 可能因移除实例、重建 HISM 或重新加载 Chunk 而改变。

更新数据

FUpdateBuildingEntityInfo

包含完整实体和 Snap Tree：

字段 说明
Entity 完整建筑实体。
Snap Tree 吸附点占用和连接数据。

该结构主要用于存档收集和世界重建。

FUpdateBuildingEntityIdInfo

用于只更新位置和 Snap Tree：

字段 说明
Entity Id 目标实体。
World Transform 新的世界变换。
Snap Tree 更新后的吸附数据。

保存与恢复

推荐流程：

CollectSaveRecords
→ 保存建筑记录
→ 读取存档
→ RebuildAll
→ 重新分配 Chunk
→ 重建运行时表现

重建时：

  • 保留 Entity Id
  • 根据位置重新分配 Chunk Id
  • 重新创建 HISM Instance 或 Building Actor
  • 将下一个 Entity ID 设置为最大现有 ID 加一

不应保存：

  • Actor 引用
  • HISM Component 引用
  • Instance Index
  • Chunk Actor 引用
  • Player Controller 或 Player State 引用

详细流程请参阅 存档与恢复。

网络同步

服务器是建筑实体数据的权威来源，负责：

  • 创建和移除实体
  • 分配 Entity Id
  • 验证建筑修改
  • 更新建筑状态
  • 同步实体变化

客户端接收实体数据后，创建或更新本地 HISM Instance 或 Building Actor。

服务器更新实体
→ 同步实体数据
→ 客户端更新运行时表现

相关文档