Building System

Purpose and Scope

The Building System in RPG Engine v6 allows players to place, snap, upgrade and destroy modular building pieces using shared character modules, DataTables and save logic.
This document targets gameplay programmers and technical designers and focuses on the runtime architecture (components, actors, snapping, rules, durability, upgrades, save integration) rather than editor setup or step‑by‑step how‑to guides.

High-Level Architecture

At a high level, the Building System consists of three main parts:

Character-side building logic – BP_BuildingComponent on the player, driven by building‑related character states and interactions.
Building actors – BP_Building_Master plus helper actors BP_B_Connector and BP_B_SnapsDetector implement snapping, validation, durability, damage and upgrades.
Data-driven configuration – DT_BuildingData and DT_CraftData define what can be built, how it behaves, what it costs, and how it can be upgraded or repaired.

All placed buildings implement the BPI_Building interface, which exposes a common API for snapping, rule checks and data access.

Character-Side Building Logic

BP_BuildingComponent

BP_BuildingComponent is the main gameplay module on the character for building.

Owns the current building mode state and selected building piece.
Reads building definitions from DT_BuildingData.
Talks to the mediator and inventory/equipment modules to check resources and consume them when placing or upgrading buildings.
Spawns preview/ghost actors and final BP_Building_Master instances according to building rules and snap detection.

Building actions are driven by a combination of State System tags and interaction logic rather than a dedicated Input Mapping Context.

The State System exposes several key states used by the building flow:

CharacterStates.UI.OpenBuildingMenu – the building menu is open (Rust‑like menu with available pieces).
CharacterStates.Building.InBuildingMode – the player has selected a building piece and is in placement mode.
CharacterStates.Building.BuildObject – active placement state; on left mouse button the selected building is actually spawned at the validated location.

These tags help synchronize UI, preview rendering, input handling and the underlying BP_BuildingComponent logic.

Building Data Model

DT_BuildingData

DT_BuildingData is the central DataTable that defines all buildable pieces.

Each row contains the following fields:

Name (Text) — localized display name of the building piece.
Description (Text) — localized description shown in UI.
Icon (Texture2D) — icon used in building menus and selection UI.
GlobalType (GameplayTag) — global category tag for the building.
Type (GameplayTag) — specific building type tag used for snapping, filtering, and validation.
Actor (Actor Class) — actor class spawned for this building piece.
InputActions (Map<InputAction, E_BuildingAction>) — maps input actions to building-specific actions such as Upgrade, Activate, StringData, or Repair.
ReceipHandle (DataTableRowHandle) — recipe used to build this piece for the first time.
NextUpdate (DataTableRowHandle) — recipe or row reference used for the next upgrade stage.
AdditionalChecks (E_BuildingRules) — extra placement rule for this building piece:
- None — no extra rule,
- OnlyOnGround — must be placed directly on ground,
- MustBeSnappedToCustomActor — the line trace must hit one of the actors listed in OnlyOnCustomBuilding.
CollisionIgnoreBuildings (GameplayTag) — building types that should be ignored during collision validation.
OnlyOnCustomBuilding (GameplayTag) — building types that this piece is allowed to snap to when custom actor snapping is required.
SnapRule (E_BuildingSnapRule) — snap category for this building, such as Base, Wall, or Floor.
Supporters (GameplayTag) — list/category of supporting building types required in detectors that use GroundDetector == Supporters.
Health (float) — maximum health of the building piece.
DestructibleObject (BP_GC_Destructable Class) — destructible object class spawned for destruction visuals/behavior.
DestructibleObjectAddTransform (Transform) — additional transform offset used when spawning the destructible object.
BuildNiagaraEffect (Niagara System) — visual effect played when the building is successfully placed.
BuildSoundEffect (Sound Base) — sound played when the building is successfully placed.
DestroyNiagaraEffect (Niagara System) — visual effect played when the building is destroyed.
DestroySoundEffect (Sound Base) — sound played when the building is destroyed.
AdditionalData (Primary Data Asset) — optional extension asset with additional building-specific data.

This table also defines all building type tags, such as:

World.Items.Buildings.Doors
World.Items.Buildings.Doorways
World.Items.Buildings.HalfWalls
World.Items.Buildings.Interactables
World.Items.Buildings.Lamps
World.Items.Buildings.SquareFoundations
World.Items.Buildings.SquareRoofDiag
World.Items.Buildings.SquareRoofDiagHalf
World.Items.Buildings.SquareRoofs
World.Items.Buildings.SquareWalls
World.Items.Buildings.Stairs
World.Items.Buildings.TriangleFoundations
World.Items.Buildings.TriangleRoofs
World.Items.Buildings.TriangleWalls
World.Items.Buildings.WallLeft
World.Items.Buildings.WallRight
World.Items.BuiSldings.Windows
World.Items.Buildings.WindowsFrames

There are no hard-coded background limitations in data: building sets are universal and not segmented per location or faction.

DT_CraftData

Actual costs for building and upgrading are defined in DT_CraftData.

Each row:

Components – array of S_DataTableRowHandles
CraftQuantity – integer; number of result items added after a successful craft
SpecialCraftCondition – S_CraftConditions; optional restriction that must be satisfied before crafting succeeds

BP_BuildingComponent queries the mediator, and resource consumption is executed by BP_EquipmentComponent, which removes items from the player’s inventory when building or upgrading.

A creative/god mode is not part of the current runtime behavior but can be added later via flags in building component or ability tags.

Building Actors and Interfaces

BPI_Building

All building actors implement BPI_Building.

This interface provides:

accessors to building data (BPI_BLD_GetBuildingData and similar methods),
hooks used by snap and validation logic,
an integration point for interaction messages (e.g. Upgrade, Repair).

Snap and detector actors rely on this interface to verify building types and rules.

BP_Building_Master

BP_Building_Master is the main building actor class.

Key responsibilities:

Holds the current Health and reads base Health and other parameters from DT_BuildingData.
Implements damage handling via AnyDamage and clamps health between 0 and max.
Calls DestroyBuilding when health reaches zero.
Runs initialization logic after spawning or after upgrade (Initialization, InitializationAfterBuilt).
Coordinates connector and detector setup via TryCollectConnectorsData and TryCollectDetectors.
Performs ground and support checks via CheckGroundDetectors and CheckNoSupport.
Exposes interaction entry points via BPI_INTER_InteractMessage and an internal Switch on E_BuildingAction for Upgrade, Repair, etc.

On destruction (DestroyBuilding), the building:

plays DestroyNiagaraEffect and DestroySoundEffect,
optionally spawns DestructibleObject with DestructibleObjectAddTransform,
calls DestroyActor to remove itself from the world,
synchronizes the result across the network via multicast events.

Repair logic is driven by events such as Multicast_Repair, which restore health and visuals server‑authoritatively.

BP_B_Connector

BP_B_Connector is an actor used as a child actor on BP_Building_Master instances.

Its purpose is to collect connector information for snapping:

At initialization, BP_Building_Master calls TryCollectConnectorsData.
This function gathers all connector child actors and fills the ConnectorLocation array.
ConnectorLocation is an array of F_ConnectorLocation.

F_ConnectorLocation fields:

Container (GameplayTag) — building type tag that this connector supports for snapping.
Transform (Transform Array) — list of world/local transforms used as snap connection points for supported building types.

Connectors define which building types can automatically snap to this building.
Example: if a wall’s ConnectorLocation only lists tags for other walls or floors, windows will not auto‑snap to this wall.

BP_B_SnapsDetector

BP_B_SnapsDetector is another actor used as a child actor on building actors.

The building holds a SnapDetectors array of FDetectorData.

FDetectorData fields:

GameplayTagContainer (GameplayTagContainer) — set of building types that this detector is allowed to search for.
GroundDetector (enum) — detector mode that defines what kind of support check is performed:
- Default
- Ground — checks whether the building stands on a Landscape actor class or an object with the Landscape tag.
- Custom
- Supporters
critical importance (bool) — defines how strongly this detector affects the final placement result; if set to true, a failed check makes the whole placement invalid.
Positions (struct) — trace positions used by the detector:
- Vector1 — start position of the trace.
- Vector2 — end position of the trace.

Runtime behavior:

SnapsDetector runs MultiBoxTraceByChannel between Vector1 and Vector2.
For each hit, it checks Hit.Actor->GetClass()->DoesImplementInterface(BPI_Building).
If yes, it calls BPI_BLD_GetBuildingData on the target and compares target building type with GameplayTagContainer.
Combined results across all detectors produce a final answer: can the building be placed and snapped at this position?

This mechanism supports complex building rules like “only place this wall if there is a valid foundation under it” or “this roof must be supported by specific wall types.”

Placement, Snapping, and Validation

Placement rules and AdditionalChecks

Placement is validated by combining:

AdditionalChecks from DT_BuildingData,
collision traces around the building mesh,
results from BP_B_SnapsDetector and BP_B_Connector.

Key rule categories:

None – only basic collision / overlap checks.
OnlyOnGround – building must rest directly on world ground; detectors use Ground mode and check for landscape or actors with the Landscape tag.
MustBeSnappedToCustomActor – traces must hit building actors of types listed in OnlyOnCustomBuilding.

If Supporters is configured and some detectors use GroundDetector == Supporters, the system checks that required supporting buildings exist under those points; if supports are destroyed later, the supported building can also be destroyed as a consequence.

Collision and overlap checks

BP_Building_Master uses:

collision components (e.g. BoxComponent as CollisionDetector),
trace functions (MultiBoxTraceByChannel and similar)

to verify that:

the building does not intersect forbidden actors or blocked geometry,
building types from CollisionIgnoreBuildings are ignored when relevant,
support and placement rules are satisfied.

There is no explicit hard limit on distance from the player or base inside BP_Building_Master; such limitations can be added at component or game mode level if needed.

Damage, Destruction, and Upgrades

Health and damage processing

Damage is handled inside BP_Building_Master:

The building stores a Health variable (float).
On Event AnyDamage, it subtracts DamageAmount from Health and clamps the result between 0 and max health.
If health reaches 0, it triggers DestroyBuilding.

DestroyBuilding:

plays destruction VFX (Niagara) and SFX,
optionally spawns a destructible actor,
calls DestroyActor to remove the building from the level,
ensures proper replication via multicast calls.

Repair is handled via events like Multicast_Repair, which restore health and visuals across all clients.

Upgrades (Upgrade)

Upgrade logic is wired through interaction and E_BuildingAction:

Player interacts with the building.
Event BPI_INTER_InteractMessage runs Switch on E_BuildingAction.
For Upgrade case, the building:
- reads the next upgrade data (NextUpdate / related building row) from DT_BuildingData,
- calls UpgradeBuilding, passing:
  - the controlling component (e.g., building component),
  - reference to the current building (Self),
  - the upgraded building class to spawn.

UpgradeBuilding:

spawns or configures the new building instance (upgraded version).
transfers transform and any necessary state (health, orientation, connections as required by implementation).
initializes the new building (e.g. via Multicast_InitializeAfterBuilt).
destroys or deactivates the old building actor.

Before upgrading, the system typically:

checks resource availability via the mediator and inventory/equipment,
validates that upgrade conditions are met (e.g., correct base piece).

Save and Load

S_BuildingSaveData and FSaveCommonData

Building persistence is integrated into the global save system via:

S_BuildingSaveData – structure storing building health and related state:
- Health (float) – current health at save time.
FSaveCommonData – shared structure that stores:
- building class,
- transform,
- other common object metadata.

Only fully placed building constructions are saved; preview/ghost or temporary states are not persisted.

Save system integration

Save/load logic lives in the game mode component:

The server gathers all relevant building actors into ObjectsOnScene.
For each building implementing BPI_Building or save interfaces, it serializes FSaveCommonData and S_BuildingSaveData.
On load, the game mode or save system:
- respawns building actors by class and transform,
- restores health and any additional data,
- re‑initializes detectors and connectors so snapping and support checks function correctly in the restored session.

This keeps the Building System aligned with the same save architecture as other interactables and systems.

Integration with Other Systems

Inventory and crafting

The Building System depends on the inventory and crafting systems:

Resource costs come from DT_CraftData.
BP_BuildingComponent communicates with the mediator to query player inventory.
BP_EquipmentComponent is responsible for actually removing items according to the recipe components.
Crafting stations themselves can be implemented as buildings (e.g., “crafting table” building types).

Built structures affect AI navigation:

Building actors have bCanEverAffectNavigation = true.
Placing or destroying buildings updates the navigation mesh (according to project settings), ensuring that AI respects walls, foundations, stairs and other structures.
The AI System does not need custom logic for buildings; it simply reacts to updated NavMesh and collision.

CCTV and other systems

While building pieces may be used as mounting surfaces for other systems (like CCTV cameras or interactables), this document does not define explicit CCTV integration.
Cameras, stations, or other world objects attach to buildings through the general interaction and placement logic defined in their own systems.

Scope and Limitations

This document covers:

character-side building logic,
DT_BuildingData and DT_CraftData usage,
building actor stack (BP_Building_Master, connectors, snap detectors),
placement rules, snapping, collision checks,
health, damage, destruction, upgrades,
save/load behavior and important integrations.

It does not cover:

detailed per-building blueprints,
full breakdown of every enum (E_BuildingRules, E_BuildingSnapRule, E_BuildingAction),
editor instructions for authoring new buildings.

Such content should live in How‑To guides (e.g., how-to-add-building-piece.md) and Reference docs for Data Assets and enums.

state-system.md
character-modules.md
inventory-and-equipment.md
interaction-and-items.md
stats-and-survival-system.md
abilities-and-unusual-skills.md
ai-system.md
crafting-system.md
save-load-system.md
map-and-minimap-system.md