Home › System plugins › AFS_Core_Snapping
System
AFS_Core_Snapping
Connector and anchor components with matrix-based snap transforms, surface alignment from a hit normal, anchor caching and ghost previews.
What it gives you
- Objects that snap into defined slots
- Surface snapping aligned to any hit normal
- Keyed connections through connector IDs
- Ghost preview while searching
Requires
Required by
9 assets61 API members
Description
Snapping is expressed as a pair. A connector lives on the movable object and searches; an anchor lives on the target and accepts. The connector computes the transform that places itself exactly on the anchor, so the object arrives correctly oriented regardless of where it was grabbed.
BPC_Connector_Anchor matches against anchors by ID, which is how you build keyed connections — a
battery that only fits its own slot. BPC_Connector_Surface instead traces for a surface and aligns
to the hit normal, which is how you place objects on arbitrary walls and tables.
An anchor cache on the game state means connectors find candidates by ID lookup rather than by searching the level every frame.
Setup
- Enable
AFS_Core_Snapping. ItsEngine.inienables Custom Depth-Stencil. - On the movable object, add
BPC_Connector_AnchororBPC_Connector_Surfaceand position it where the object should meet the target. - On the target, add
BPC_Anchorand position it. - Set Connector ID on the connector and add it to the anchor's Connector IDs To Allow.
AFS_Core_Snapping_setup.pngA connector on the object and an anchor on the target
Usage
Keyed connections
Give the connector a Connector ID and list it in the anchor's allow list. Leave the allow list empty to accept anything.
Surface placement
Use BPC_Connector_Surface and set Rotate On Surface to control whether the object keeps its
rotation or aligns to the normal.
Previewing
Turn on Show Snapping Preview for a ghost of the snapped result while the object is held, and Show Anchors On Search to reveal compatible anchors.
AFS_Core_Snapping_result.pngThe battery held beside its slot, snap preview showing where it will land
Key properties
| Property | When to change |
|---|---|
Search Distance | How near the object must be before a destination is offered |
Release Type | Whether releasing snaps and attaches, snaps only, or does nothing |
Connector IDs To Allow | To key an anchor to specific connectors |
Rotate On Surface | Surface connectors: keep rotation, align to normal, or align and face player |
Wall Rotation Adjustment | When the object's forward axis is not its natural facing |
Extending
Derive from BPC_Connector and override searchForAcceptableDestination and getDesiredRelativeTransform for a new snapping rule.
Multiplayer notes
Multiplayer
Attachment replicates through Server_AttachConnectorToComponent and its detach counterpart, so every client sees the same connection.
Example map
Map_Examples_Snapping shows keyed anchor snapping with a battery and lightbulb, plus surface snapping.
Troubleshooting
Nothing snaps. The connector ID is not in the anchor's allow list, or Search Distance is shorter than the gap.
The object arrives rotated wrongly. Adjust Wall Rotation Adjustment, or reposition the connector so its axes match the anchor's.
API reference
Every blueprint asset in this plugin. Expand an asset to see its members.
Components
BPC_Anchor13 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| var | ConnectorIDsToAllowSettings | name[] | Connector IDs this anchor accepts. Leave empty to accept any connector; fill it in to build keyed connections such as a battery that only fits its own slot. |
| var | ConnectorShouldAttachSettings | bool | Whether a connector physically attaches to this anchor, or merely snaps its transform without parenting. |
| var | SphereRadiusSettings | float | Radius within which a searching connector will consider this anchor. |
| fn | DrawDebugSettings | () | Draws the anchor's search sphere in the world, for tuning placement. |
| fn | IsConnectorAllowedState | (AnchorConnector: BPC_Connector_Anchor, out Allowed: bool) | Returns whether the given connector is permitted by this anchor's allow list. |
| fn | getAnchorCacheCache | () → BPC_AnchorCache | Returns the game-state anchor cache used to look anchors up by ID without searching the level. |
| fn | IsAvailableState | () → bool | Returns whether this anchor is currently free, meaning nothing is already attached to it. |
| event | SetOccupyAnchor | (Set: bool) | Marks the anchor as occupied or free, so other connectors skip it while it is in use. |
| event | SetAttachedConnector | (Connector: BPC_Connector_Anchor, Set: bool) | Records or clears the connector currently attached to this anchor. |
| event | ConnectorSetSearching | (Set: bool, ConnectorAnchor: BPC_Connector_Anchor) | Called when a connector starts or stops searching, so the anchor can show or hide its preview. |
| event | CorrectListOfHelpers | () | Reconciles the anchor's preview helper actors with the connectors currently searching. |
| event | AnchorHovered | (ConnectorAnchor: BPC_Connector_Anchor) | Called when a searching connector selects this anchor as its current best candidate, so it can highlight. |
| event | OnDestroyed_Event | (DestroyedActor: Actor) | Internal handler that removes this anchor from the cache when its owner is destroyed. |
BPC_Connector20 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| var | ReleaseTypeSettings | E_Snap_AttachType | What happens when the object is released near a valid destination: snap and attach, snap only, or nothing. |
| var | SearchDistanceSettings | float | How far the connector looks for a valid destination while being carried. |
| var | ShowSnappingPreviewPreview | bool | Whether a ghost preview of the snapped result is shown while searching. |
| var | SoundLocationFoundSound | SoundBase | Sound played when a valid snap destination is first found. |
| var | SoundLocationLostSound | SoundBase | Sound played when the connector loses its snap destination. |
| var | Sound_DetachSound | SoundBase | Sound played when the connector detaches from a destination. |
| var | Sound_AttachSound | SoundBase | Sound played when the connector attaches to a destination. |
| fn | getDesiredRelativeTransformTransform | () → Transform | Returns the transform the owning actor should take relative to the destination. Override in a subclass to change how the object aligns. |
| fn | searchForAcceptableDestinationTrace | (out ComponentToAttachTo: SceneComponent, out DesiredDestination: Transform, out Priority: float, out SocketToAttachTo: name) | Looks for the best snap destination within search distance and returns it with a priority score. Override to implement a new snapping rule. |
| fn | getAllActorsToIgnoreTrace | (out ActorsToIgnore: Actor[]) | Returns actors excluded from the destination search, normally the carried object and the player. |
| fn | getAnchorCache | () → BPC_AnchorCache | Returns the anchor cache held on the game state, adding it the first time it is asked for. Every connector shares that one cache, which is how a connector finds candidate anchors without searching the level. |
| fn | getSnapTransformTransform | (InConnector: BPC_Connector, InWorldAnchorTransform: Transform, out OutWorldSnapTransform: Transform) | Computes the world transform that places this connector exactly on the given anchor transform. |
| fn | getAnchorTransformTransform | (InConnector: BPC_Connector, InAnchor: BPC_Anchor, out OutWorldSnapTransform: Transform) | Computes the world transform that places this connector on the given anchor component. |
| event | AttachConnectorToComponent | (Transform: Transform, Component: SceneComponent, SocketName: name) | Attaches the owning actor to the target component at the given transform and socket. |
| event | DetachConnectorFromActor | () | Detaches the owning actor from whatever it is currently snapped to. |
| event | PositionToRelativeTransform | (Transform: Transform, TargetSceneComponent: SceneComponent, TargetSocket: name, UseMotion: bool) | Moves the owning actor to the given relative transform, optionally animating the movement rather than snapping instantly. |
| event | Server_AttachConnectorToComponent | (RelativeTransform: Transform, Component: SceneComponent, SocketName: name) | Replicated attach, so every client sees the object snapped to the same destination. |
| event | Server_DetachConnectorFromActor | () | Clears this connector's stored connection on the server, which replicates the break out to every client. Called by Detach Connector From Actor; the detach sound is played locally by the caller, so calling this on its own breaks the link silently. |
| event | ConnectorFoundDesiredLocation | (Transform: Transform, ComponentToAttachTo: SceneComponent) | Fires when a valid destination is found, carrying the transform and target component. Bind to it to drive custom preview visuals. |
| event | SetSearch | (Search: bool) | Starts or stops searching for a destination. Normally driven by the grip system when the object is picked up and released. |
BPC_Connector_Anchor9 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| var | ConnectorIDSettings | name | Identifier matched against an anchor's allow list. Use it to make a connector fit only certain anchors. |
| var | ShowAnchorsOnSearchAnchors | bool | Whether compatible anchors reveal themselves while this connector is searching, so the player can see where the object fits. |
| fn | searchForAcceptableDestination | (out ComponentToAttachTo: SceneComponent, out DesiredDestination: Transform, out Priority: float, out SocketToAttachTo: name) | Searches the anchor cache for the closest compatible anchor within search distance. |
| event | OnConnectorAttached_Event | (Connector: BPC_Connector, AttachedToComponent: SceneComponent) | Internal handler that marks the target anchor occupied once attachment completes. |
| event | OnConnectorDetached_Event | (Connector: BPC_Connector, DetachedFromComponent: SceneComponent) | Internal handler that frees the anchor when the connector detaches. |
| event | PositionToRelativeTransform | (Transform: Transform, TargetSceneComponent: SceneComponent, TargetSocket: name, UseMotion: bool) | Moves the owner onto the anchor, animating when requested. |
| event | AttachConnectorToAnchor | (Anchor: BPC_Anchor) | Attaches this connector to a specific anchor, bypassing the search. |
| event | ConnectorFoundDesiredLocation | (Transform: Transform, ComponentToAttachTo: SceneComponent) | Fires when a compatible anchor is found. |
| event | SetSearch | (Search: bool) | Starts or stops the anchor search, revealing compatible anchors when configured to. |
BPC_Connector_Surface7 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| var | RotateOnSurfaceSettings | E_Snapping_Rotate | How the object orients once placed on a surface: keep its rotation, align to the surface normal, or align and face the player. |
| var | RequiresTagSettings | name | Actor tag a surface must carry to accept this connector. Leave empty to allow any surface. |
| var | WallRotationAdjustmentSettings | float | Extra yaw applied when snapping to a vertical surface, for objects whose forward axis is not the natural facing direction. |
| fn | searchForAcceptableDestination | (out ComponentToAttachTo: SceneComponent, out DesiredDestination: Transform, out Priority: float, out SocketToAttachTo: name) | Traces for a surface within search distance and returns the snap transform aligned to its normal. |
| fn | getDesiredRelativeTransform | () → Transform | Returns the transform placing the owner flat against the found surface. |
| fn | getSurfaceTransformTransform | (InConnectorSurface: BPC_Connector_Surface, InHitPoint: Vector, InNormal: Vector, out OutTransform: Transform) | Computes the world transform that seats this connector on a surface at the given hit point and normal. |
| fn | alignRotationToNormalTransform | (InNormal: Vector, InRotation: Rotator, out OutRotation: Rotator) | Rotates a rotator so its up axis matches the given surface normal while preserving its facing as closely as possible. |
Helper
BPC_AnchorCache4 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| fn | AddAnchorToCacheCache | (ID: name, Anchor: BPC_Anchor) | Registers an anchor under an ID so connectors can find it without searching the level. |
| fn | RemoveAnchorFromCacheCache | (ID: name, Anchor: BPC_Anchor) | Takes an anchor out of the list registered under the given identifier, so connectors stop offering it as a snap target. Anchors call this themselves when they are deactivated or destroyed. |
| fn | getAllAnchorsForIDCache | (ref const ID: name, out Anchors: BPC_Anchor[]) | Returns every cached anchor registered under the given ID. |
| fn | getSnapLocationHelperSnap Helper | () → BP_Helper_SnapLocation | Returns the shared helper actor used to visualise snap locations. |
BP_Helper_MeshCopy_Anchor4 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| var | SphereRadiusSettings | float | Radius of the anchor indicator sphere. |
| var | Anchor | BPC_Anchor | The anchor this preview represents. |
| var | Color_HoveredStyle | LinearColor | Colour used when this anchor is the connector's current best candidate. |
| event | AnchorHovered | () | Switches the preview to its hovered colour. |
BP_Helper_MeshCopy_Preview0 members
No editor-visible members; this asset configures defaults only.
BP_Helper_SnapLocation0 members
No editor-visible members; this asset configures defaults only.
Libraries
FL_Snapping4 members
| Kind | Name | Signature | Description |
|---|---|---|---|
| fn | GetSnapTransform | (InConnector: BPC_Connector, InWorldAnchorTransform: Transform, __WorldContext: Object, out OutTransform: Transform) | Returns the world transform that places a connector exactly on the given anchor transform. |
| fn | GetSurfaceTransform | (InConnectorSurface: BPC_Connector_Surface, InNormal: Vector, InHitPoint: Vector, __WorldContext: Object, out OutTransform: Transform) | Returns the world transform that seats a surface connector on a surface at the given hit point and normal. |
| fn | GetAnchorTransform | (InConnector: BPC_Connector, InAnchor: BPC_Anchor, __WorldContext: Object, out OutTransform: Transform) | Returns the world transform that places a connector on the given anchor component. |
| fn | AlignRotationToNormal | (InNormal: Vector, InRotation: Rotator, __WorldContext: Object, out OutRotation: Rotator) | Rotates a rotator so its up axis matches a surface normal while preserving its facing as closely as possible. |