Building World Subsystem¶

UBuildingWorldSubsystem is the runtime building subsystem for the current world. It primarily provides Building Entity queries, save-data collection, and building world reconstruction APIs.

Building creation, movement, and removal should be initiated through UBuildingBuildComponent.

Note

Some functions in this class are declared as public but are intended only for internal communication between plugin components. Therefore, they are not documented as recommended public APIs.

Basic Information¶

Item	Description
Class	`UBuildingWorldSubsystem`
Base Class	`UWorldSubsystem`
Lifetime	Same as the current `UWorld`
Primary Purpose	Entity queries, save-data collection, and world reconstruction
Blueprint Support	Available for selected APIs
Multiplayer Authority	Reconstruction and clearing operations should be performed by the server

Getting the Subsystem¶

Blueprint¶

Get World Subsystem
→ Building World Subsystem

C++¶

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

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

Entity Query APIs¶

API	Description
`TryFindEntity`	Queries a Building Entity by Entity ID.
`GetAllEntity`	Returns all Building Entities in the current world.
`CollectSaveRecords`	Collects building records used for saving and reconstruction.

TryFindEntity¶

Queries building data by Entity ID.

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

Type	Name	Data Type	Description
Param	`EntityId`	`int32`	The Entity ID of the building to query.
Param	`OutEntity`	`FBuildingEntity&`	Receives the Entity data when the query succeeds.
Return	`bFound`	`bool`	Returns `true` when the corresponding Entity is found.

GetAllEntity¶

Returns all Building Entities from the currently registered Chunks.

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

Type	Name	Data Type	Description
Return	`Entities`	`TArray<FBuildingEntity>`	An array containing the Building Entities in the current world.

This API is suitable for:

Debugging building data
Project-specific queries
Editor tools
Runtime statistics

For save operations, prefer CollectSaveRecords().

CollectSaveRecords¶

Collects complete save records from the current building world.

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

Type	Name	Data Type	Description
Return	`SavedRecords`	`TArray<FUpdateBuildingEntityInfo>`	Data used to save and reconstruct the building world.

Recommended workflow:

Collect Save Records
→ Write the records to the project save data
→ Load the save data
→ Rebuild All

The project does not need to save HISM Components, Instance Indexes, Chunk Actors, or building Actor references manually.

For more information, see Save and Load.

World Management APIs¶

API	Description
`RebuildAll`	Rebuilds the entire building world from saved records.
`RemoveAll`	Clears all building runtime data from the current world.

RebuildAll¶

Rebuilds the building world from saved building records.

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

Type	Name	Data Type	Description
Param	`SavedRecords`	`TArray<FUpdateBuildingEntityInfo>`	Building records collected by `CollectSaveRecords()`.
Return	—	`void`	No return value.

This API reconstructs:

Building Entities
Chunks
HISM Instances
Actor-mode buildings
Runtime mappings between Entities and Chunks
Building data contained in the saved records

In multiplayer games, this function should be called by the server:

The server reads the save data
→ Rebuild All
→ The plugin synchronizes the building data
→ Clients reconstruct the building representations

Warning

Clients should not independently read the same world save data and call RebuildAll(). Doing so may create duplicate buildings or Entity ID conflicts.

RemoveAll¶

Clears all building runtime data from the current world.

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

Type	Name	Data Type	Description
Return	—	`void`	No return value.

This API clears Building Entities, Chunk Actors, and related runtime indexes.

It is suitable for:

Switching to another world save
Resetting the building world
Clearing the current data before loading another building dataset

In multiplayer games, this function should be called by the server.

Entity Events¶

Entity events are used to listen for changes to networked building data.

These events currently use native multicast delegates and can only be bound from C++.

Event	Parameter	Trigger
`OnBuildingNetEntityAdded`	`const FBuildingEntity&`	After a Building Entity is added.
`OnBuildingNetEntityChanged`	`const FBuildingEntity&`	After the building position or primary data changes.
`OnBuildingNetEntityRemoved`	`const FBuildingEntity&`	After a Building Entity is removed.
`OnBuildingNetEntityDataChange`	`const FBuildingEntity&`	After Entity Tags or Attributes change.

C++ Binding Example¶

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

Callback function:

// Copyright 2026 Zhiying Li. All Rights Reserved.

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

These events do not currently use BlueprintAssignable, so they cannot be bound directly in Blueprints.

Recommended Entry Points¶

Operation	Recommended Entry Point
Enter or exit Build Mode	`UBuildingBuildComponent`
Start placing a building	`UBuildingBuildComponent`
Confirm a building	`UBuildingBuildComponent`
Edit or move a building	`UBuildingBuildComponent`
Remove a building	`UBuildingBuildComponent`
Query an Entity	`UBuildingWorldSubsystem`
Get all Entities	`UBuildingWorldSubsystem`
Collect save records	`UBuildingWorldSubsystem`
Rebuild the building world	`UBuildingWorldSubsystem`
Query building data assets	`UBuildingSubsystem`

Undocumented Internal APIs¶

The following APIs are primarily intended for internal plugin communication and are not recommended for direct use by standard projects:

Category	Examples
Internal building entry points	`ConfirmBuild`, `ConfirmMoveBuild`, `ConfirmRemoveBuild`
Server implementations	`ConfirmBuild_ServerOnly`, `ConfirmMoveBuild_ServerOnly`
Chunk management	`RegisterChunk`, `UnRegisterChunk`, `GetOrCreateChunkByLocation`
Network callbacks	`OnNetEntityAdded`, `OnNetEntityChanged`, `OnNetEntityRemoved`
Actor binding	`TryBindBuildActorToChunk`, `RegisterPendingBuildActor`
Request Actor	`SetRequestActor`, `ClearRequestActor`, `GetRequestActor`
Internal Snap Tree	`FindSnapTree`, `RemoveSnapTree`

These APIs may change as the plugin's internal implementation evolves and should not be used as the project's primary integration points.

Difference from Other Subsystems¶

Type	Lifetime	Responsibility
`UBuildingSubsystem`	`GameInstance`	Building data asset loading, caching, and queries.
`UBuildingWorldSubsystem`	`World`	Entities, Chunks, save data, and runtime data in the current world.

A simple distinction:

Type	Manages
`UBuildingSubsystem`	How a building type is configured.
`UBuildingWorldSubsystem`	Which buildings currently exist in the world.

For building asset APIs, see Building Subsystem.

Multiplayer¶

Operation	Recommended Execution Location
`TryFindEntity`	Server or client-local data
`GetAllEntity`	Server or client-local data
`CollectSaveRecords`	Server
`RebuildAll`	Server
`RemoveAll`	Server
Entity event listeners	Server or client

Entity queries on a client return the local building data that has already been synchronized to that client.

Server data should be treated as the final authoritative result.

Troubleshooting¶

Issue	What to Check
The Subsystem cannot be obtained	Check whether the current `World` is valid.
`TryFindEntity` returns `false`	Check whether the Entity ID exists and whether its Chunk is registered.
`GetAllEntity` returns an empty array	Check whether buildings have been created or restored in the current world.
`CollectSaveRecords` returns an empty array	Check whether it is being called in the correct world and on the server.
Buildings are duplicated after `RebuildAll`	Check whether the reconstruction API is being called more than once.
Clients do not display restored buildings	Check whether `RebuildAll()` was called by the server.
Entity events cannot be bound in Blueprints	These events currently support C++ only.
Subsystem data disappears after changing levels	A `UWorldSubsystem` is destroyed together with its current world.