The distance matching component is a useful tool that facilitates triggering distance matching situations and tracking distance to markers. Depending on your settings it can also be used to automatically detect and trigger distance matching or, the different distance matching situations can be triggered manually.
Add the Distance Matching Component
To add the component, open your character blueprint and in the top left corner click ‘+AddComponent’ and search for distance matching.
Component Settings
This section explains the settings on the distance matching component which can be modified in the details panel after selecting the component.
Automatic Triggers - Check this box if you want the distance matching component to automatically trigger distance matching situations. Keep in mind that the logic used for automatic triggers is a fixed setup based on UE4’s Character Movement component. If you want to trigger distance matching situations with your own logic, keep this unchecked.
Note: Only Starts, Stops and Plants can currently be triggered automatically from the distance matching component. TurnInPlace, Jump and Pivot type animation need to be manually triggered.
Distance Tolerance - How close the character needs to be to the distance marker before it is considered to be ‘reached’.
Min Plant Detection Angle - The minimum angle between the character’s current movement and acceleration vectors required to trigger a plant.
Min Plant Speed - The minimum speed of the character required to trigger a plant
Min Plant Accel - The minimum acceleration of the character required to trigger a plant
Note: Plant detection is reliant on the movement component velocity and acceleration vectors. By comparing the angle between these vectors it is possible to determine if the desired movement is in a different direction compared to the current movement.
Manually Triggering Distance Matching
It is likely that you will want to trigger distance matching situations with your own game logic instead of the built in functionality. However, this does not mean you have to make your own distance matching component. Instead you can turn off ‘Automatic Triggers’ and manually trigger distance matching situations with your own logic.
The functions shown in the image below can be called in your character blueprint at runtime to facilitate this:
Trigger a Start
A start animation is an animation where the character is idle and then starts moving in a direction. The distance is measured from the character ‘back’ to the distance marker.
DistanceMatchType - Backward
DistanceMatchTrigger - Start
DistanceMatchBasis - Positional
Trigger a Stop
A stop animation is an animation where the character is moving and then slows to idle. The distance is measured from the character’s current position ‘forward’ to the distance marker.
DistanceMatchType - Forward
DistanceMatchTrigger - Stop
DistanceMatchBasis - Positional
Trigger a Plant
A plant animation is an animation where the character is moving in one direction and then changes to another direction (e.g. 180). Before the plant point is reached the distance is measured from the character’s current position forward to the distance marker. After the plant point is reached, the distance is measure from the character’s current position backward to the distance marker.
DistanceMatchType - Both
DistanceMatchTrigger - Plant
DistanceMatchBasis - Positional
Trigger a Jump
Jump animation is self explanatory and the distance marker is placed at the peak of the jump. Before the peak is reached the distance is measured from the character’s current position vertically forward to the peak of the jump (Z-axis only). After the peak the distance is measured from the characher’s current position vertically backward to the peak of the jump.
DistanceMatchType - Both
DistanceMatchTrigger - Jump
DistanceMatchBasis - Positional (Z-Only)
Trigger a Turn In Place
Turn in pace animations occur when the character is idle and turns to face a different direction. The distance is measured is the angle in degrees from the character’s current rotation backward to their starting rotation at the beginning of the turn.
DistanceMatchType - Backward
DistanceMatchTrigger - TurnInPlace
DistanceMatchBasis - Rotational (Z-Only)
Trigger a Pivot
A pivot animation occurs when the character is moving and pivots to face a different direction. The distance is measured as an angle in degrees from the character’s current rotation backward to their starting rotation at the beginning of the pivot.
DistanceMatchType - Backward
DistanceMatchTrigger - Pivot
DistanceMatchBasis - Rotational (Z-Only)
Extracting Data in Animation Blueprint
In order to inform your animation graph, data needs to be extracted from the distance matching component at runtime. There are two main things that need to be extracted:
Whether to trigger a state transition for distance matching
The distance to the marker
To extract distance to the current marker call the following function in your animation event graph:
To check if any distance matching situations were triggered this frame you can call the following function to get the trigger and consume it so that it won’t be triggered again next frame. This can help assist with animation state transitions when distance matching situations are triggered, however, you can use your own logic for this if you like.
The ‘Trigger Transtiion variable is an enumeration that can take on the following values:
None - No trigger
Start - A start has been triggered
Stop - A stop has been triggered
Jump - A jump has been triggered
TurnInPlace - a turn in place has been triggered
Pivot - a pivot has been triggered.