Asset Snapper Documentation
Overview
The Asset Snapper is an Editor Only Tool that allows users to define custom points on Static Meshes, referred to as "Snap Points". Each Snap Point consists of a few properties, such as Location, Rotation, and Tags. Using these Snap Points, we can very easily snap any actor containing Static Mesh Components in the Level Editor, as well has snap together the components themselves in the Blueprint Editor.
The Snap Points themselves have zero runtime impact during an actual game session in the Editor, and are completely stripped out during packaged builds.
If there is enough demand, there is the possibility that it can be extended to allow for runtime (in-game) functionality.
Quick Tips
Power users utilizing [Alt + Drag] to duplicate Actors in conjunction with Snapping [S] will encounter an issue involving the Editor's 'Play in Editor (Simulated)' Mode default key bind [Alt + S]. The simplest solution to avoid triggering this Mode accidentally while using [Alt + Drag + S] is to rebind the default key bind for 'Play in Editor (Simulated)'.
Creating / Editing Snap Points
Snap Points are created in the Static Mesh Editor.
Enabling the Snap Point Toolbar and the Snap Point Manager
The Snap Point Toolbar and Manager can be enabled by checking the boxes in the 'Window' menu of the Static Mesh Editor.
The Snap Point Manager
The Snap Point Manager is the main window where you can add, edit, duplicate, set locations and rotation values, and delete Snap Points. You can also add Snap Points from Snap Point Vertex Mode (more on this later).
By default, Snap Points are hidden in the Static Mesh Editor due to limitations in the Engine. You can enable them by clicking on "Show SnapPoints".
Selecting Snap Points
If you select a Snap Point via the Manager, the transform widget in the Viewport may be used to edit position and rotation manually.
There is a pull request currently in review that fixes some issues with the Static Mesh Editor, and allows you to directly click on points in the viewport window. If you are using a custom engine build, you can read more here
Editing Snap Points
In the Snap Point manager, you can directly select Snap Points and edit their translation, rotation, and tag list.
In the list on the right of the Snap Point Manager, you can select multiple Snap Points by holding Shift and Clicking. It is possible to delete, and copy the selected Snap Points via the context menu. You can even bulk-edit/multi-edit Snap Points.
Snap Point Multi-Edit
If you select multiple Snap Points in the Snap Point Manager, you will be able to multi-edit their properties. You can easily set the Rotation or Location for these points.
Tag editing also works in multi-edit mode. However, only common tags between all selected Snap Points are be shown. These common tags can be deleted and renamed. You can also add a new tag to all of the selected points this way.
Snap Point Vertex Mode also works during Multi-Edit.
Snap Point Vertex Mode
In Snap Point vertex mode, you can directly click on mesh vertices to use their translation/rotation as a basis for Snap Points. A point can be selected by clicking on a vertex. Multiple points can be selected by holding shift and clicking, and points can be removed by holding control and clicking.
A BLUE box appears after selecting a point, showing you the current average location/rotation of all selected Snap Points.
In the Snap Point Toolbar, there are options to create a Snap Point at the location [A], add a Snap Point at the location with rotation [Shift + A], and to set the current selected Snap Point's Location [T] and Rotation [Y].
All Hotkeys can be changed in the settings.
Level / Blueprint Editor Snapping
After you have Snap Points setup, snapping is extremely easy! Simply hit the [S] key while dragging, and if your selection contains Actors whose components have Snap Points, the Snap Points appear on the Selected Mesh and all surrounding meshes.
When close enough to other Snap Points that fulfill the set Snap Settings criteria, blue lines appear between Snap Points indicating the current Snap to be performed when the drag operation is released. If you wish to cancel / ignore the snap, simply release the [S] key before releasing the drag.
Tag Matching and Filtering
If tag matching is enabled, only Snap Points with matching Tags are considered for snapping.
If tag filtering is also enabled in the settings, only Snap Points that pass the whitelist/blacklist are allowed as Snap Point candidates.
Resnap
There are two ways to perform re-snapping operations. The first is through the auto-resnap boolean flag, which attempts to re-snap the selection of objects together after a snap to minimize error. The second is through manual invocation. A manual re-snap can be triggered in the Level and Blueprint editors by pressing [,]. All selected objects will attempt to recursively re-snap together in order to eliminate as much error as possible.
Pivot Selection (Level Editor Only)
You use created Snap Points to quickly set selection transformation pivots in the level editor. By holding down the [D] key, all Snap Points in the current selection are shown. Clicking on any of these points moves the transformation pivot to the selected Snap Point.
Snap Settings
The Snap Operation itself is fully configurable. You can tweak various parameters for your drag, such as snap distance, the minimum number of points for a snap to be considered, the maximum number of points, the alignment axis, and tag matching settings.
The Snap Settings window can be opened via any Editor window, by going to the active Editor's 'Window' menu.
General Settings
Snap Distance
Controls the distance threshold in which points can be snapped to.
Min Snap Points
The minimum amount of Snap Points that must match before considering a Snap.
Max Snap Points
The maximum amount of Snap Points that can be considered in a Snap.
Tag Match
A boolean flag controlling whether tags should be considered during Snapping.
Snap Extent Distance
Controls the distance in which nearby Snap Points can be seen. Not to be confused with Snap Distance.
Visualize Extent
A boolean flag that controls whether or not the Snap Point Extent box is visualized in the Editor during drags.
Auto-Resnap
A boolean flag that controls whether or not auto-resnap is performed automatically when snapping multiple objects together.
Pivot Adjustment
Level Editor exclusive.
There are three options, None, Pivot, and Primary. In Pivot mode, the snapped selection has its transformation origin set to the pivot point post-snap. The Pivot point in single-point mode is the Snap Point itself, and in two-point and three point modes it is the middle of the Snap Points. In Primary mode, the transformation origin is moved to the Snap Point that was shown as Primary during the Snap.
Snap Distance
Controls the distance threshold in which points can be snapped to.
Min Snap Points
The minimum amount of Snap Points that must match before considering a Snap.
Max Snap Points
The maximum amount of Snap Points that can be considered in a Snap.
Tag Match
A boolean flag controlling whether tags should be considered during Snapping.
Snap Extent Distance
Controls the distance in which nearby Snap Points can be seen. Not to be confused with Snap Distance.
Visualize Extent
A boolean flag that controls whether or not the Snap Point Extent box is visualized in the Editor during drags.
Auto-Resnap
A boolean flag that controls whether or not auto-resnap is performed automatically when snapping multiple objects together.
Pivot Adjustment
Level Editor exclusive.
There are three options, None, Pivot, and Primary. In Pivot mode, the snapped selection has its transformation origin set to the pivot point post-snap. The Pivot point in single-point mode is the Snap Point itself, and in two-point and three point modes it is the middle of the Snap Points. In Primary mode, the transformation origin is moved to the Snap Point that was shown as Primary during the Snap.
Point Settings
Single Point Snap
In single point mode, the operation simply moves the dragging objects Snap Point to the target. It may also be optionally aligned via the Snap Point's axis, with adjustable offsets.
Two Point Snap
In two point mode, the operation snaps and aligns the dragging objects to the two target Snap Points. The dragging object may be optionally scaled to match the target points. The dragging object may be optionally aligned to the primary Snap Points axis, after it has been lined up properly, with adjustable offsets.
Three Point Snap
In three point mode, the operation snaps and aligns the dragging objects to the triangle formed by the three matching Snap Points. If the triangle formed by the two sets of Snap Points are identical, then the result is an exact snap. Otherwise, the midpoints of the triangles are aligned, and the primary Snap Point on the dragged object is aligned towards the target (after the dragged object is placed onto the same plane).
Resnap Settings
Resnap Tolerance
The distance tolerance the points must be at to re-snap together. Generally this is super low (1cm) but it can be set higher for more generic re-snap operations with the [,] key.
Min Snap Points
The minimum amount of Snap Points needed for a re-snap.
Max Snap Points
The maximum amount of Snap Points allowed in a re-snap.
Tag Match
A boolean flag to allow or disallow tag matching during re-snaps.
Use Single Point Settings
A boolean flag to use the Single Point settings during the re-snap for single-point snaps.
Use Two Point Settings
A boolean flag to use the Two Point settings during the re-snap for two-point snaps.
Tag Filter
Use Tag Filter
A boolean flag to enable or disable the tag filter.
Tag Filter is Blacklist
Whether or not to treat the Tag Filter List as a Whitelist or a Blacklist.
Tag Filter List
A list of Tags to be used as a Snapping Whitelist or Blacklist.
Import / Export
Snap Points can be exported and imported from any Static Mesh asset via the right click menu in the Content Browser. The files are exported in the JSON file format, and can be easily edited by hand if needed.
Static Mesh Editor Fixes (Advanced)
This is for those who are using a custom engine build, and would like to get the Static Mesh Editor fixes early.
There are currently a small number of usability bugs with the Static Mesh Editor and the Asset Snapper. This is due to a limited API set. There is a pull request which fixes a lot of these issues, which you can find here and patch it into your Engine build locally.
After building the engine with the fixes above, you can simply set the C++ define located in Plugins/AssetSnapper/Source/AssetSnapper/Public/AssetSnapperDefines.h to 1.