TrueKaizoku/KLSv3.5-Docs.md

## KLSv3.5-Docs.md

      
    Raw
  

              KLSv3.5-Docs.md
            
          
- Overview
The Kai locomotion System (KLS) Version 3.5, is an Unreal Engine (5.1+) plugin that aims to provide the fastest and easiest way to create high-quality character locomotion without compromising character control.
IMPORANT : SYSTEM DOES NOT USE ROOT MOTION TO MOVE CHARACTER , ROOT MOTION IS ONLY USED TO EXTRACT DATA FROM ANIMATION , CHARACTER MOVES WITH CHARACTER MOVEMENT COMPONENT.
This is achieved through the usage of:

Distance matching, which aims to match the right animation frame and/or play rate with the character physics movement.
Rotation matching, which injects the rotation from the animations into the character physics rotation.
Animation warping, which changes animation rotation and stride scale to match character movement,
This greatly reduces and nearly eliminates foot sliding.

To retain more control over character movement and rotation and to extend upon the existing functionalities of the default character movement component, this version of the plugin utilizes its own custom character movement component which is required for the asset to function correctly. Aside from a custom CMC1, this plugin utilizes Linked Animation Instance features in the engine to allow for runtime switching of locomotion and masking (Overlay) animation sets.


- Animation System Explanation
The animation system in KLSv3 consists of 2 parts.

Base Animation Instance :

This animation instance has the animation logic, i.e. the animation state machines and the rules to switch between states. However, this animation Instance has no reference to an animation. it uses the linked animation instances to provide it with the animations that play in each of its states.

Linked animation instances Layers :

The base animation instance uses these nodes in its graph. The base animation instance does not add animation or logic within these animation nodes.
Instead, it relies on another animation instance that implements the same linked animation layer interface, but instead of having any kind of animation logic in its animation graph, this animation instance would just implement the logic of each of the layer nodes and then use the "Link Animation Layer" function to link the layers that contain animations into the base animation instance.
This is the system used in Epic Games' Lyra project,
Lyra Animation System Documentation
Animation Blueprint Linking Engine Documentation
KLSv3 Uses 2 Linked animation instances, one for switching locomotion animations and one for switching masking animations.
- Locomotion Linked Animation Instance

The Locomotion Animation Instance has in it the individual animation states logic such as Start state, Loop state, Stop State , etc..
Filled inside of the layers interface.

The Only thing that gets filled in this blueprint is the Locomotion data asset which holds a reference to all used animation and the settings of this specific locomotion set.

-  Locomotion Data Asset

The data that is populated is animation sequences, and the data that is extracted to be used later is the root motion data from those animation sequences. This is the reason why Root Motion IS Necessary In the Locomotion animations. Without Root Motion, there is no data that can be extracted and used later to play the animations correctly. To create Locomotion Data Asset, right-click in the content browser, select Miscellaneous/Data Asset and search for KLS Locomotion Data in the new window.


-  Masking Linked Animation Instance

KLS Masking System is encapsulated inside of this linked animation instance.
The core of the system in the custom Animation Node  Per Body Part Mask Node.

Just Like The Locomotion Linked Anim Instance , this one has a data asset with the masking animations for standing , crouching and in
air. This Data asset is used to extract the blend weights of all body parts offline as curves and use them later at runtime.

- Masking Data Asset

To Create a new Masking Data Asset, Right click in the content browser, Select Miscellaneous/Data Asset. then in the new window search for KLS Masking Data.


- Custom Character Movement Component
The plugin uses a custom CMC¹ , whose purpose is to efficiently replicate certain values that the animation system needs, and it extends the functionality of the base class slightly.
You can change your character's movement component to use the KLS class by clicking on the character movement component in the character blueprint and changing the class to KLSCharacterMovementComponent in the details Panel.
NOTE : For the Rotation in the system to work as expected. Make sure that the Character Blueprint Has "Use Controller Rotation Yaw" set to false.

Functionalities :


Ability to set the character speed at runtime without causing any correction when there's latency (ping).


Ability to set a Multiplier for acceleration when pivoting (this gives more weight to character when changing direction based on the speed without needing to have low ground friction). Can be found in CMC¹ class defaults.


Ability to change the character rotation mode (facing direction or strafing)


Ability To Toggle Aiming, this changes rotation mode to strafing when it's on. and also used to blend in the aiming poses from locomotion data asset Idle And Turn In Place sections.


Separate acceleration to use when crouching


Separate Rotation Rate to use when strafing (negative value makes rotation instant)


- How To Use The Plugin With Your Project
FIRST , Make Sure You Changed Your Character Movement Component To Use KLS Character Movement Component. (Check Custom Character Movement Component Section).
Step 1 - Setting up Your Skeleton

Adding required animation curves:

To add required curves navigate to an animation from your skeleton.
You can create new animation from pose by selecting create new asset and selecting animation asset/from current pose.
Inside the animation navigate to Animation Modifier Window
and add, then, apply the animation modifier "AM_AddCurves".
(add image here)

Add Curves Animation Modifier:
This Animation Modifier holds a list of KLS required curves. By default this modifier will add the default curves to the skeleton, not the animation itself. You can however use this modifier to bulk add curves and their values to animations if needed for any use case.

Adding the Required Animation Slots to the skeleton:

Currently there's no way to bulk add these slots so it'll have to be done manually. Double Check The slot names after adding them.

If you can find the "Anim Slot Manager" window, you can open  it by navigating to "Window/Anim Slot Manager".

Adding Blend Masks:

Blend Masks are used in the animation system to let you define which chain of bones constitute a body part.

List of All the Blend Masks And The Bone chain that Are Part Of it :


PelvisMask :

pelvis bone


SpineMask :

All spine bone


LegsMask :

Right leg chain from thigh_r to ball_r
Left leg chain from thigh_l to ball_l
Both Right and Left IK Bones, IK_foot_root bone is not part of the mask


HeadMask :

Neck bones chain
Head bone


RightArmMask :

Right arm chain from clavicle_r to hand_r
ik_hand_gun and ik_hand_r


RightHandMask :

All Right hand Finger Bones


LeftArmMask :

Left arm chain from clavicle_l to hand_l
ik_hand_l


LeftHandMask :

All Left hand Finger Bones (Keeping List Simple)


UpperBody :

All Upper Body Bones From Pelvis To Head. (You can blend in the spine bones weights however you like)


Step 2 - Creating Animation Blueprints

With the Skeleton being ready now we can move on to creating the animation blueprints.
MAKE SURE you Setup your skeleton before creating any animation blueprints.
It is Highly Recommended to never edit the plugin's animation blueprints directly. this is to make sure that updates won't break any changes you make.
There are 3 Animation Blueprints To Use:


KLS_BaseAnimBp: This is the base animation blueprint that will be used with your character mesh.

Right click in the content browser select Animation/Animation Blueprint.
In New Window Select your skeleton (Already Setup) and create a new Animation Blueprint from class "KLS_BaseAnimBP".


Can be found inside Plugins/Kai Locomotion Content/ Animation_Blueprint/Base_AnimInstances.


Navigate to your character Blueprint and Set this new AnimBP as your character Mesh Animation Blueprint.


If You are Using A Skeleton Different From Ue4 Skeleton, Open The Created AnimBP and Make Sure "Show Inherited Variables" is Ticked on


Search For "Anim Nodes Bones" Variable And Make Sure Bone Names Are Correct, Example Ue5 Skeleton has 2 extra spine bones, make sure you add them in "Orientation Warping Spine Bones" and "AimOffset Bone Definitions".

NOTE : These Exist In All 3 Animation Blueprints, Base AnimBP, Base Linked AnimBP and Base Mask AnimBP.

Create KLS_BaseLinkedAnimBP : This is the locomotion linked animation instance which will be linked through blueprint functions.
Check Step 4 Linking Locomotion Layer .

Right click in the content browser select Animation/Animation Blueprint.
In New Window Select your skeleton (Already Setup) and create a new Animation Blueprint from class "KLS_BaseLinkedAnimBP".


Can be found inside Plugins/Kai Locomotion Content/ Animation_Blueprint/Linked_AnimInstances.

If You are Using A Skeleton Different From Ue4 Skeleton, Open The Created AnimBP and Make Sure "Show Inherited Variables" is Ticked on


Search For "Anim Nodes Bones" Variable And Make Sure Bone Names Are Correct, Example Ue5 Skeleton has 2 extra spine bones, make sure you add them in "Orientation Warping Spine Bones" and "AimOffset Bone Definitions".

NOTE : These Exist In All 3 Animation Blueprints, Base AnimBP, Base Linked AnimBP and Base Mask AnimBP.

Create KLS_BaseMaskAnimBP : This is the Masking linked animation instance which will be linked through blueprint function call (Check Step 6 : Linking Masking Layer)

Right click in the content browser select Animation/Animation Blueprint.
In New Window Select your skeleton (Already Setup) and create a new Animation Blueprint from class "KLS_BaseMaskAnimBP".


If You are Using A Skeleton Different From Ue4 Skeleton, Open The Created AnimBP and Make Sure "Show Inherited Variables" is Ticked on


Search For "Anim Nodes Bones" Variable And Make Sure Bone Names Are Correct, Example Ue5 Skeleton has 2 extra spine bones, make sure you add them in "Orientation Warping Spine Bones" and "AimOffset Bone Definitions".

NOTE : These Exist In All 3 Animation Blueprints, Base AnimBP, Base Linked AnimBP and Base Mask AnimBP.
Step 3 - Setting Up Locomotion Data Asset

Locomotion data Asset needs to be filled with at least the minimum required animations.


An idle Animation.


2 Turn In Place Animations :
Turn Right 90 degrees and Turn Left 90 degrees These animations need to have root motion rotation.


4 Start Animations :


These 4 animations need to have root motion in them. they are start forward, start right, start left and start backward. It is better that these animations are a couple of steps in them, if your start animations are short you can create an animation composite² that has the start animation and the loop animation in that direction.
If the final pose of the start is the same as the first pose of the loop you can edit the start time of the loop to make the poses line up.

need to have the Sync marker modifier applied to them

4 Loop Animations :

These 4 animations need to have root motion in them which will affect their play rate and stride scale (how big the footsteps are) based on the root motion data and the character physics movement at runtime.
need to have the Sync marker modifier applied to them

4 Stop Animations :

These 4 animations need to have root motion.
Settings


Settings Section is Split into 3 :


Standing Settings :


Walk Gait Entry Speed : The Speed of the character to consider him Walking


Run Gait Entry Speed : The Speed of the character to consider him Running , Start playing run gait animations.


Walk Gait Entry Speed : The Speed of the character to consider him Sprinting , Start playing sprint gait animations.


Stop Distance ThreshHold : At this Distance Character will be considered stopped and distance matching will play animation in normal playrate When Standing.

Walk Rotation Interp Speed : KLS Uses its own rotation calculations to rotate character during locomotion. this interp speed is used when character is Walking .
Run Rotation Interp Speed : KLS Uses its own rotation calculations to rotate character during locomotion. this interp speed is used when character is Running .
Sprint Rotation Interp Speed : KLS Uses its own rotation calculations to rotate character during locomotion. this interp speed is used when character is Sprinting .


Crouching Settings :


Crouch Blend In Time : Time it takes for crouch idle to blend In


Crouch Blend Out Time : Time it takes for crouch idle to blend Out


Stop Distance ThreshHold : At this Distance Character will be considered stopped and distance matching will play animation in normal playrate when Crouching .


Rotation Interp Speed :  KLS Uses its own rotation calculations to rotate character during locomotion. this interp speed is used when character is Crouching .


In Air Settings:

Min Distance To Land : The minimum required distance away from landing point to start playing the landing prediction animation.


Rotation Interp Speed :  KLS Uses its own rotation calculations to rotate character during locomotion. this interp speed is used when character is In the Air .


Standing Section


Idle And Turn In Place : 

Idle Pose : Standing locomotion idle pose, only the first frame of this will be used. (requires at least 1 additive animation with it.
Additive Animations : These Animations are Additive³ and can play randomly. Need to have at least 1 animation.
Aim Pose : Tis is treated like a mask animation with body part separation each with its own override and additive weights
Aim Blend In time : Time it takes for aiming pose to blend in.
Aim Blend Out time : Time it takes for aiming pose to blend out.
Turn In Place Anims : 2 turn in place animation of 90 degrees right and left.
Min Angle To Trigger TIP : If rotation offset between character and camera is at or higher than this value, while idling, turn in place transition will trigger. (this is clamped between 10 and 90 degrees)
Turn In Place Speed : How fast to play the turn in place animations.


Loop Animations : 

Play Rate Clamp : Min And Max Play rate for Loop , start, and pivot animations.
Stride Scale Clamp : Min And Max Procedural Foot Step scale for Loop , start, and pivot animations.
Walk/Run/Sprint :

Lean Intensity Multiplier : A multiplier that effets lean intensity in each Gait.
Average Speed : this is the average speed of the walking animations. this is there to give you a general idea what is ideal speed for these animations
Forward , Right , Left and Backward : Loop Animations


Start Animations : 

Walk/Run/Sprint :

Strafe Starts : Required Animations , 4 directional start animations.
Has Rotating Starts : If Ticked Animation system will use rotating starts when not strafing.
Rotating starts : 4 rotating starts animations , Right, Left 90 degrees and Right , Left 180 degrees.


Stop Animations : 

Walk/Run/Sprint

Right Foot Up : Required Animations Default Stop Animations, if you have different stops for right foot up use them here.
Use Per foot Stop : When Enabled Left foot Up Stop animations need to be filled.
Left Foot Up : These Animations are used when "Use Per Foot Stop" is Active.


Pivot Animations[^4] : 

Walk/Run/Sprint

Has Strafe Pivot Animations : Turn on to fill strafe pivot animations.
Strafe Pivots : 4 directional pivot Animations.
Has Rotating Pivots :  Turn on to fill Rotating pivot animations.
Strafe Pivots : 4 Rotating pivot Animations. Right, Left 90 and Right, Left 180.
*If You Do Not Have Pivot Animations The System will Use Stops And Starts To Act As Pivots


If you do have any of the extra supported animations such as rotating starts and pivot ⁴ animations you can fill them in their respective section. if you don't have them you can leave the tick boxes off and there's no need to add anything. For example if you have rotating pivots only there's no need to fill strafing pivots. there's also no need to fill all them in a certain gait if you don't have the animations.

Crouching Section


Just Like the Standing Section , the only difference is that the crouching section does not have 3 different speed gaits, just one.
Jumping Section


Jump Section has 2 parts:

Jump : Jumping animation in KLS can be more than 1 per data asset and KLS Custom Jump Selector is responsible for selecting which to play based on gameplay tags.

Custom Jump Selector :

To Create a Custom Jump Selector , right right in an empty space in the content browser and select "Blueprint Class" .

In the new window, click on "All Classes" then search for KLSCustomJumps.

This class has 1 overridable function Select Jump Animations that provides some information as input and has an output of gameplaytag. This is used if you want to use different jumps , based on jump direction or falling distance etc...

+ Jump Animations : this is a TMap of Gameplay Tag and KLSJumpSet. The gameplay tag is used to identify each jump set and then uses the gameplay tag the selector returns to get the right jump animation.


Key (GameplayTag) : The Gameplay Tag That represents this jump set
KLSJumpSet : This struct holds all the information required for this jump.

Can Blend With Other Sets : if true, when changing between motion sets it will allow this to blend with the new set's jump. If false, even when changing motion sets this jump will keep playing and won't blend.
Jump Animation : The Full jump animation. If you only have cut animations you can use a composite[^2] to make them a full animation.
Take off time : the time in the full jump animation where character feet first get off the ground.
Apex Start Time : This is the Jump Apex Time[^7] - 0.1.
Apex End Time : This is the Jump Apex Time[^7] + 0.1. (Can be improved to take in only apex time instead of start and end).
Landing Time : This is the time in the full jump where character feet first touch the ground again. (The Rest of the animation of this time is the Landing animation of this jump)
Fall Loop : Loop Animation of the falling motion.


Land : You can have multiple land animation in KLS and they can even be played as montages (hard landing, roll etc..). Same as the jump this is accomplished with the use a blueprint class that has an overridable function and return a gameplay tag.

Custom Land Selector :

To Create a Custom Jump Selector , right right in an empty space in the content browser and select "Blueprint Class" .

In the new window, click on "All Classes" then search for KLSCustomLand.

This class has 1 overridable function Select Land Animation that provides some information as input and has an output of gameplaytag. This is used if you want to use different land , based on total falling distance, falling speed etc...

Land Animations : this is a TMap of Gameplay Tag and KLSLandSet. The gameplay tag is used to identify each land set and then uses the gameplay tag the selector returns to get the right land animation.


Key (GameplayTag) : The Gameplay Tag That represents this Land set
KLSLandSet : this struct holds all the information for a land animation.

Land Anim : The Landing Animation which can be played in 2 different ways, either as an additive animation (this is done dynamically, do not set this animation to additive) or as a dynamic montage.
Play As Montage : If true this animation will play as a montage in BaseLayer slot .
Walk additive alpha : Needs Play Montage To Be False To Edit , the alpha of the additive land when playing walk animations.
Run additive alpha : Needs Play Montage To Be False To Edit , the alpha of the additive land when playing run animations.
Sprint additive alpha : Needs Play Montage To Be False To Edit , the alpha of the additive land when playing sprint animations.
Blend In Time : Needs Play Montage To Be True To Edit Blend in time of Montage.
Blend Out Time : Needs Play Montage To Be True To Edit Blend out time of Montage.
Play Rate : Needs Play Montage To Be True To Edit , Montage play rate
Blend Out Trigger Time : Needs Play Montage To Be True To Edit , at what time should montage start blending out.
If set to negative value , the blend out time trigger will be Montage Length - Blend out time.
In Time To Start Montage At : Time To Start Montage (if you have full jump animation that has landing portion that w\you want to play as montage use this to start from the Landing Time)


Applying Animation Modifiers

Easiest Way to apply animation modifiers is the open the content browser and select all the animations that you want to apply the modifier to , then right click and select animation modifier

In the new window select your modifier, if you click on it you can edit the default values of the modifier then apply.

Foot Sync Animation Modifier:

This modifier expects root motion in the animations

Foot Sync Animation Modifier is responsible for adding sync markers to animations that are used only for blending between animations. their main purpose is to identify when in the loop animations should we start from based on the markers inside of it. Having loop animations that have multiple steps in them improves the blending.


Reapply Post owner Change : this is left to false.
Bone Definitions :

Root Bone.
Feet Definitions : An Array to represent each foot name and the sync marker name that will be used in the animations for this foot.


Extraction Mode :

Use Directions Names : If Set To True The modifier will no longer use root motion to define the direction , instead it will use the " Direction Names" variable along with the animation it's being applied to to find direction.


Directions Names : Names for each direction to check in the animation name in order to determine its direction. for example if an animation has "Fwd" in its name then it's forward animations.


Step 4 - Linking Locomotion Animation Blueprint

To Link Locomotion Animation Layer, the function "Try Link Anim Layer"  should be used, and Unlink if invalid is ticked off, this would mean if the given class is invalid nothing will happen.


Mesh : Your Character Mesh. The Mesh That Uses Base Animation Blueprint.
In Class : The Linked Locomotion Animation Blueprint you want to use
Unlink Group If Invalid : Should Be Ticked Off For Locomotion Layers
Group Name : Can be Left None, Has No Effect When Unlink Group If Invalid Is False.

Without a linked Locomotion layer the base animation blueprint will only produce a T-Pose. You Should Always Have a Linked Layer , At begin Play you need to link your base/Unarmed locomotion layer.
You can Switch it Later by linking a new animation blueprint class with a different Locomotion data Asset.
This function Is NOT a replicated function. make sure to call this in a replicated event if you have a multiplayer project. Begin play is a replicated event.
Step 5 - Setting Up Masking Data Asset


The Masking data asset has 3 sections :
Standing Section

The Standing Section of the Masking data Asset has An idle Animation and 4 Loop animations for each gait. You can use the same animation in the entire Data asset if you want to. What matters is making sure you set the masking weights to your ideal weights. (this usually requires some testing to find the perfect weights for each mask and locomotion animations combination)

The Masking animation has 3 parts:


Animation asset : The Animation to use for masking


Masking Pose : Only the Frame At this Masking Pose is used for masking not entire animation


Masking Weights : The Weights that will be used for masking , they have have 2 values for each body part :

The Mask Weight which represents how much should the masking animation pose override the locomotion animation pose for that body part.
The Additive Weight which represents how much movement of the original locomotion animation should be kept after applying the masking weight.


Only The arms body parts have a choice to select which space you want to blend the arms in.in most cases you want the arms to blend in local space so they would follow the spine rotation.


Crouching Section


The Crouching Section is the same as the Standing section, Except the moving mask has 1 speed gait instead of 3.
In Air Section


In Air Masking Section has only 2 animations jump which will mask locomotion animation when character up velocity is positive and falling which plays when velocity is negative.
Step 6 - Linking Masking Animation Blueprint

To Link Masking Animation Instance, the function "Try Link Anim Layer"  should be used, and Unlink if invalid is ticked on . since masking can be completely removed this should only be ticked on be masking and will unlink the current masking animation layer if the given class is invalid.


Mesh : Your Character Mesh. The Mesh That Uses Base Animation Blueprint.
In Class : The Linked Masking Animation Blueprint you want to use
Unlink Group If Invalid : Should Be Ticked On For Masking Layers
Group Name : Should Use Function "Get Masking Group Name" To Fill This.

This function Is NOT a replicated function. make sure to call this in a replicated event if you have a multiplayer project.


- Playing Montages With Masking System
KLS uses multiple slots in its animation system , added when Setting up the skeleton.
The special slots are the body part slots, to play a montage on a body part you need to select the desired body part slot
And then add the override and additive curves for that body part and the space blend curve⁵.
Each body part has 4 curves:


KLS_BodyPart (Example "KLS_Pelvis") is the override weight curve.


KLS_BodyPart_Add (Example "KLS_Pelvis_Add") is the additive weight curve


KLS_BodyPart_MS (Example "KLS_Pelvis_MS) is the Mesh Space weight curve. This Curve Should Be Set to 1 when used or not use at all if Local Space Blend is Desired . Pelvis, Legs and Spine are usually blended in mesh space.


KLS_BodyPart_LS (Example "KLS_Pelvis_LS") is the Local Space Weight curve. This Curve Should Be Set to 1 when used or not use at all if Mesh Space Blend is Desired . Hand, Arms and Head are usually blended in local space.


List Of All Masking Curves Masking System Uses:

PelvisMask
PelvisMask_Add
PelvisMask_LS
PelvisMask_MS
SpineMask
SpineMask_Add
SpineMask_LS
SpineMask_MS
HeadMask
HeadMask_Add
HeadMask_LS
HeadMask_MS
LegsMask
LegsMask_Add
LegsMask_LS
LegsMask_MS
RightArmMask
RightArmMask_Add
RightArmMask_LS
RightArmMask_MS
RightHandMask
RightHandMask_Add
RightHandMask_LS
RightHandMask_MS
LeftArmMask
LeftArmMask_Add
LeftArmMask_LS
LeftArmMask_MS
LeftHandMask
LeftHandMask_Add
LeftHandMask_LS
LeftHandMask_MS


Step 7 - Adding Your Own Custom Animation States:

KLS Support extending the anim graph logic with custom animation states such as swimming, flying, climbing etc.. without needing to modify the plugin animation blueprint.


First , Create a new Animation blueprint for your skeleton, Doesn't Need to have any specifc parent, you can use the default Animation blueprint class or any custom class you have.


Second , Implement Interface "KLS_CustomStates_Layer_Interface" in the created animation blueprint, Under Class Defaults/ Implemented Interfaces.


Finally, You Can Add Whetever Logic you want in the layer Custom States (Appears after implementing the interface).


Best Way To Use Is to Save The input Pose First


Then Create A New State Machine And Call Entry State Locomotion State And Plug The Saved Pose In This State, from there you can add more states as your game needs.

IMPORANAT : DO NOT FORGET to link this new animbp alongside the Base linked animBP.
  

- Integrations
Lyra Integration:

Tutorial Video

Footnotes


CMC stands for Character Movement Component ↩ ↩²


Animation Composites ↩


Open The animation you want to make additive and in its Class defaults Change it from No Additive To Local additive. Then switch it to Additive from current pose and you can leave it at frame 0. ↩


Pivot Animations are Animations where character changes running direction , there are strafing pivots and rotating pivots each are respectively used when character is strafing or not. ↩


There are 2 spaces to blend a body part in when playing through a montage, either Local Space which is represented by LS or Mesh Space which is Represented by MS. ↩