Snapping System

The snapping system aligns a building preview with Sockets on nearby buildings.

Snapping affects only the placement process and does not participate in structural support evaluation. Whether a building is supported is determined by its collision relationships after placement.

Note

Buildings placed without snapping can still receive support.

A successful snap does not necessarily mean that the building has valid structural support.

Workflow

Update building preview
→ Search for candidate buildings
→ Collect Sockets
→ Check Groups, distance, and direction
→ Calculate the snap Transform
→ Update the building preview

Item	Description
Socket	The snap position and rotation defined on a Static Mesh.
Snap Point	The snapping rules associated with a Socket.
Snap Group	Restricts which Sockets can connect to each other.
Connection Axis	Defines the connection direction used by a Socket.

Snapping Settings

Open:

Edit → Project Settings → Building System → Snapping

Setting	Default	Description
Enable Snapping	Enabled	Determines whether global Socket snapping is enabled.
Snap Distance	50 cm	The candidate search range and maximum accepted Socket distance.
Snap Direction Tolerance	-0.9	The maximum allowed Dot value between two connection directions.
Snap Points	Empty	Snap Point definitions used by the project.
Available Snap Groups	Empty	Snap Groups available to the project.

For other project-level settings, see Plugin Settings.

Snap Distance

Snap Distance controls both candidate searches and precise distance filtering.

First Search

Using the current Aim hit location as the center:

1. Collect nearby buildings within Snap Distance.
2. Check the distance from each candidate Socket to the Aim hit location.
3. Only Sockets within Snap Distance can become candidates.

Second Search

Using the Ghost building's Box Bounds:

1. Expand the Box by Snap Distance and collect nearby buildings.
2. Check the distance from each candidate Socket to the edge of the Ghost Box.
3. Only Sockets within Snap Distance can become candidates.

Snap Distance
→ Expand the component query range
→ Limit the precise accepted Socket distance

Overlap queries use component Bounds, so the actual distance of each Socket must still be checked after the search is complete.

Candidate buildings are usually queried through the Building Object Channel. For collision configuration, see Collision Configuration.

Direction Matching

The system calculates the Dot value between the connection directions of two Sockets.

Dot <= Snap Direction Tolerance

A candidate passes the direction check only when this condition is satisfied.

The default value is -0.9. The closer the value is to -1, the more closely the two directions must face directly opposite each other.

Snap Points

Each Snap Point contains:

Field	Description
Socket Name	The name of the corresponding Socket on the Static Mesh.
Groups	One or more compatible Groups to which the Socket belongs.
Connection Axis	The primary connection axis used by the Socket.
Is Local	Determines whether the connection direction is calculated using the Socket's local rotation.

Socket Name must exactly match the name defined on the Static Mesh.

A consistent naming convention is recommended:

Snap_Left
Snap_Right
Snap_Top
Snap_Bottom
Snap_Front
Snap_Back

Connection Axis

Connection Axis specifies which axis of the Socket is used as its connection direction.

It is generally recommended to use:

(1, 0, 0)

This uses the Socket's local X axis.

Sockets in different positions can use the same Connection Axis, while their actual directions are controlled through Socket Rotation.

The local X axis of Snap_Left points to the left.
The local X axis of Snap_Right points to the right.

Note

Connection Axis defines the primary connection axis. It does not indicate where the Socket is located on the building.

Is Local

When enabled, the system calculates the actual connection direction using the Socket's local rotation.

When disabled, the connection direction is treated in world space. The Ghost building usually needs to be rotated before it can satisfy the direction-matching requirement.

Keeping this setting enabled is generally recommended.

Snap Groups

Two Sockets must share at least one Group before the system continues with distance and direction checks.

For example:

Socket	Groups
Snap_Left	Horizontal
Snap_Right	Horizontal
Snap_Top	Vertical
Snap_Bottom	Vertical

With this configuration:

• Left and right Sockets can match.
• Top and bottom Sockets can match.
• Horizontal and vertical Sockets cannot match.

A Socket can belong to multiple Groups:

Groups = Horizontal, Decoration

Note

Sharing the same Group only allows two Sockets to participate in matching. They must still pass the distance and direction checks.

Configuration Steps

1. Create Sockets on the Static Mesh.
2. Adjust each Socket's position and rotation.
3. Add matching names to Snap Points.
4. Configure Groups.
5. Configure Connection Axis.
6. Ensure that the building uses the correct Building Object Channel.
7. Enter Build Mode and test snapping.

Basic example:

Socket Name	Groups	Connection Axis
Snap_Left	Horizontal	(1, 0, 0)
Snap_Right	Horizontal	(1, 0, 0)
Snap_Top	Vertical	(1, 0, 0)
Snap_Bottom	Vertical	(1, 0, 0)

The actual connection direction is determined by Socket Rotation.

Snapping and Structural Support

Feature	Snapping System	Support System
Purpose	Aligns the building preview	Determines whether the structure is valid
Usage Stage	During placement	After placement or when the structure changes
Evaluation Basis	Socket, Group, distance, and direction	Collision contact between buildings
Triggers Collapse	No	Yes

For structural support, see Structural Support and Collapse.

API

Snap-related APIs are primarily provided by Building Build Component.

See Snap Candidate APIs.

Troubleshooting

Issue	What to Check
Nearby buildings cannot be found	Check Enable Snapping, Snap Distance, and Building Object Channel.
A building is found but snapping does not occur	Check the Snap Group, Socket distance, and direction.
The snap direction is incorrect	Check Socket Rotation, Connection Axis, and the direction tolerance.
A Socket is not recognized	Check whether the Socket name matches exactly.
The preview snaps to the wrong position	Reduce Snap Distance or use more specific Snap Groups.
Buildings cannot receive support after snapping is disabled	Check the building collision and support channels.