Chunk System¶

The Chunk system groups buildings in the world by spatial region.

Each Chunk manages the Building Entities, rendering components, and network synchronization data within a specific area, preventing all buildings from being concentrated in a single Actor or component.

The Chunk system is primarily used to:

Manage large numbers of Building Entities
Group HISM buildings for rendering
Manage Actor-mode buildings
Limit the scope of individual updates and rebuilds
Organize building network synchronization
Provide a foundation for saving and regional loading

Note

Chunks are an internal spatial management mechanism used by the building system.

Under normal usage, projects do not need to create or manage Chunk Actors directly.

Basic Structure¶

The building system determines which Chunk a building belongs to based on its world position.

Each Chunk usually corresponds to a building rendering and synchronization Actor that manages the buildings within that area.

Building Subsystem
├── Chunk A
│   ├── HISM Buildings
│   ├── Actor Buildings
│   └── Building Entity Data
├── Chunk B
│   ├── HISM Buildings
│   ├── Actor Buildings
│   └── Building Entity Data
└── Chunk C
    ├── HISM Buildings
    ├── Actor Buildings
    └── Building Entity Data

While the current world is running, each building records its Chunk ID, which is used to locate the corresponding Chunk.

Chunk ID is runtime spatial management data and should not be treated as a stable building identifier across world loads or save data.

Chunk Actor¶

Each Chunk Actor manages the building representations within its corresponding area.

Its main responsibilities include:

Item	Description
Building Entities	Stores the basic data of buildings within the Chunk.
HISM Components	Batch-renders buildings that use the same module.
Actor Buildings	Manages independent Actors such as doors, containers, and workbenches.
Instance Mappings	Stores the relationships between Building Entities and HISM Instances.
Network Synchronization	Synchronizes building additions, changes, and removals within the Chunk.

Projects should normally operate on buildings through the APIs provided by the building system instead of modifying Chunk Actors directly.

Building Entities and Rendering Representations¶

The Building Entity data stored in a Chunk is separate from the building's rendering representation.

A Building Entity usually stores:

Entity ID
Chunk ID
Building Data Asset ID
World Transform
Building attributes
Building owner
Other runtime data

The rendering layer creates the following from the Entity data:

HISM Instances
Building Actors
Corresponding visual states

This design allows the building system to manage building data without depending on specific rendering objects.

Network Synchronization¶

In multiplayer games, Building Entity data is managed by the server.

The server is responsible for:

Creating Building Entities
Validating building operations
Modifying building data
Removing Building Entities
Synchronizing Chunk data

After receiving Entity data, clients create or update the corresponding building representations locally.

HISM Instances are not replicated directly as independent network Actors. Instead, clients update their local HISM representations from the synchronized Building Entity data.

The basic workflow is:

The server creates a Building Entity
→ The synchronization data of the corresponding Chunk is updated
→ Clients receive the building change
→ Clients create an HISM Instance or Actor locally

This approach avoids creating an independent replicated Actor for every standard building module.

Chunk Size¶

Chunk size can be configured under:

Edit → Project Settings → Building System → Chunk

Smaller Chunks¶

Smaller Chunks generally have the following characteristics:

Fewer buildings in each Chunk
Fewer buildings affected by local updates
More Chunk Actors
Greater Chunk management overhead

Larger Chunks¶

Larger Chunks generally have the following characteristics:

Fewer Chunk Actors
More buildings within each Chunk
More instances processed during a single rebuild
Larger synchronization data for each Chunk

There is no fixed Chunk Size suitable for every project. It should be tested according to:

Map size
Building density
Typical base size
Common building module dimensions
Number of multiplayer users

Chunks and Save Data¶

The save system should generally store Building Entity data instead of directly saving HISM Components or Actor references.

Recommended data to save includes:

Entity ID
Chunk ID
Building Data Asset ID
World Transform
Building attributes
Owner data
Project-specific data

The basic loading workflow is:

Read Building Entities
→ Create or locate Chunks
→ Restore Entity data
→ Rebuild HISM Instances or Actors

HISM Instances and Building Actors are runtime representations and can be recreated from Entity data.

Usage Recommendations¶

Choose an appropriate rendering mode according to the building's purpose:

Scenario	Recommendation
Large numbers of repeated walls, floors, and roofs	Use `HISM`.
Doors, containers, and workbenches	Use `Actor`.
Large-scale, low-density building areas	Consider increasing the Chunk size.
Small-scale, high-density building areas	Test small or medium-sized Chunks.
Production save data already exists	Avoid changing `Chunk Size`.
A stable building reference is required	Use Entity ID.
Access to the current HISM Instance is required	Query the Instance Index at runtime.

Do not determine the final Chunk Size based only on theoretical values.

Test it using the project's actual building counts, map scale, and multiplayer environment.

For project-level Chunk settings, see Plugin Settings.