Traits can be very useful as they enable the user to separate different animations or animation sections into different states using a set of traits. At runtime, the user can specify a set of traits at any given time (as node input) and the motion matching node will only ever play animations that have the specified Traits.
To Trait Or Not To Trait
At the end of the day, traits are simply a different way of managing animation state. The same outcome could be achieved by simply creating a new state within your animation state machine. This would be easier to read, debug and understand. However, adding more states makes the graph more complex and difficult to manage. A balance is recommended and how you go about this is up to you.
Declaring Traits
In order to markup animations with traits, they first need to be declared in the project settings. On the UE4 editor menu toolbar, navigate to Edit->Project Settings. Scroll down to the ‘Plugins’ heading on the left panel of the settings window and click on ‘Motion Symphony.
In this section you will find a ‘Trait Names’ list where you can declare the names of traits. It is recommended to keep the trait names simple and avoid spaces / special characters. There is currently a limit of 64 trait name declarations so use them wisely.
Once your desired traits have been declared you are ready to use them with tags and at runtime. You can come back and add traits as necessary. Just remember that if you delete any trait declarations you may break trait references somewhere in your project so be careful when doing so.
Adding Traits to Animations
There are two ways to add traits to animations:
Add them to an animation as a whole (most common method)
Add them via tags to specific sections of animations.
Whole of Animation Traits
To add traits to an entire animation, simply select the animation in the MotionData editor, navigate to the ‘Tags’ heading and add all applicable traits to the TraitName list. The example shown below adds the trait’s ‘Injured’ and ‘RedTrait’
Note: The trait names specified here must exactly match one of the declared trait names, otherwise it will not have an effect.
Tag Based Traits
To add traits to sections of an animation, right click on a tag track (after selecting an animation) and choose TagSection/TagTrait. This will create a yellow tag that you can resize and move on your timeline. Resize and position the trait tag as desired to mark the appropriate section/s of the animation
Select the tag and set the tag name in the contextual details panel on the bottom left corner of the editor. A single trait tag can only have one trait. Add more trait tags to apply multiple traits to an animation section.
Creating And Managing Trait Queries
In order to use traits at runtime, we need to convert our trait strings into a trait query so that it can be used as an input to the motion matching node. Multiple traits can be active at any given time so this helps combine them in an efficient manner.
Create the Query
Start by creating a variable in your animation blueprint of type ‘Motion Trait Field’. This will create an empty trait query which you use to store traits in an efficient manner.
Initialize the Query
To initialize the query use the ‘GetTraitHandle’ functions from the Motion Symphony blueprint function library as shown below. You can either initialize it with a single trait name or an array of trait names.
Adding Traits
Once a trait field is initialized, more traits can be added to it without resetting the entire query. To do this use one of the ‘AddTrait’ functions from the Motion Symphony blueprint function library as shown below: You can add a single trait by name, add multiple traits by an array of names or add traits from another motion trait field.
Removing Traits
Traits can also be removed from a Motion Trait Field at runtime without resetting the entire query. To do this use one of the ‘RemoveTrait’ functions from the Motion Symphony blueprint function library as shown below. You can remove a single trait by name
Note: How you decide to manage your trait queries is up to you. You could cache them all on ‘BeginPlay’ as separate queries or you could use a single query and add or remove traits during runtime.
Feeding Traits Into The Motion Matching Node
Once your trait query has been setup as you desire, it can be used as an input into any motion matching node via the ‘Required Traits’ input / binding.
As your ‘Motion Trait Field’ is modified and changed in the event graph at runtime, the motion matching node will respond accordingly.