Skip to content

Building Entities

A Building Entity is the core data structure used by the plugin to represent a placed building.

Each building corresponds to an FBuildingEntity, which stores its identifier, world transform, building asset, owner, and persistent state.

HISM Instances and Building Actors are only runtime representations created from the Entity.

Note

FBuildingEntity represents the logical data of a building.

Actor references, HISM Components, and Instance Indexes should not be used as stable building identifiers.

Data Structure

Field Description
Entity Id The unique identifier of the Building Entity.
Chunk Id The runtime Chunk to which the building currently belongs.
World Transform The building's world-space location, rotation, and scale.
Buildable Asset Id The Building Data Asset used by the building.
Owner Id The player, faction, NPC, or system that owns the building.
Entity Data Additional persistent state associated with the building.

Entity ID

Entity Id is used to query, move, modify, and remove buildings.

When rebuilding from save data, the plugin preserves the existing Entity Id values and sets the next available ID to:

Highest existing Entity Id + 1

Chunk ID

Chunk Id is used for runtime spatial partitioning, rendering, and network management.

Chunks are reassigned from World Transform during rebuilding, so a Chunk ID should not be treated as a long-term stable identifier.

For more information, see Chunk System.

World Transform

World Transform stores the complete world-space transform of the building:

  • Location
  • Rotation
  • Scale

The plugin uses this transform to recreate the HISM Instance, Building Actor, and collision representation.

Buildable Asset ID

Buildable Asset Id is the Primary Asset Id of the asset that defines the building.

The plugin uses it to locate the corresponding Building Data Asset and read:

  • Rendering mode
  • Static Mesh
  • Actor Class
  • Preview Mesh
  • Other building configuration

For more information, see Building Data Assets.

Owner ID

Owner Id consists of an owner type and a stable string ID.

Field Description
Type The owner type.
Id The stable identifier of the owner.

The following owner types are supported:

Type Description
None No valid owner.
Player A player.
Faction A faction or team.
NPC An NPC.
System The game system or world.

Owner Id does not store references to a Player Controller, Player State, Pawn, or Actor.

The project should provide an ID that remains stable across reconnections and save operations. Player ownership is usually provided through the Building Owner Provider interface.

Entity Data

Entity Data stores the persistent state of an individual building, such as:

  • Building health
  • Gameplay Tags
  • Custom attributes
  • Project-specific extension data

Note

Static configuration shared by a building type should be stored in its Building Data Asset.

The state of an individual placed building should be stored in Entity Data.

Entities and Runtime Representations

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

Only Entity Id is a stable building identifier.

An Instance Index may change when an instance is removed, an HISM is rebuilt, or a Chunk is reloaded.

Update Data

FUpdateBuildingEntityInfo

Contains the complete Entity and Snap Tree:

Field Description
Entity The complete Building Entity.
Snap Tree Snap-point occupancy and connection data.

This structure is primarily used for save-data collection and world rebuilding.

FUpdateBuildingEntityIdInfo

Used when only the position and Snap Tree need to be updated:

Field Description
Entity Id The target Entity.
World Transform The new world transform.
Snap Tree The updated snapping data.

Save and Load

Recommended workflow:

CollectSaveRecords
→ Save the building records
→ Read the save data
→ RebuildAll
→ Reassign Chunks
→ Rebuild runtime representations

During rebuilding, the plugin:

  • Preserves Entity Id
  • Reassigns Chunk Id according to the building position
  • Recreates the HISM Instance or Building Actor
  • Sets the next Entity ID to the highest existing ID plus one

The following data should not be saved:

  • Actor references
  • HISM Component references
  • Instance Indexes
  • Chunk Actor references
  • Player Controller or Player State references

For the complete workflow, see Save and Load.

Network Synchronization

The server is the authoritative source of Building Entity data and is responsible for:

  • Creating and removing Entities
  • Assigning Entity Id
  • Validating building modifications
  • Updating building state
  • Synchronizing Entity changes

After receiving Entity data, clients create or update their local HISM Instances or Building Actors.

The server updates an Entity
→ Entity data is synchronized
→ Clients update the runtime representation