Add a New Item Animation Layer

This tutorial walks through extending Lyra's modular animation system to implement holding a new item for your character. Motion uses the same animation system as the Lyra Sample Game.

You'll create a child animation blueprint for the item, wire it into the logic that equips it, and verify smooth transitions when equipping it in Motion.

Why Lyra Layers?

Lyra ships with ALI_ItemAnimLayers, ABP_ItemAnimLayersBase, and item-specific child blueprints (rifle, pistol, etc.). Motion builds on this structure so each holdable item can ship its own locomotion poses and aim offsets while reusing shared logic.

Prerequisites

• Familiarity with Unreal Engine's Animation Blueprint system
• A system, or atleast a plan, on how you intend to manage the state of which item is currently being held. (i.e. Inventory System or Gameplay Abilties)

Overview

1. Duplicate ABP_UnarmedAnimLayers or create a child blueprint of ABP_ItemAnimLayersBase, the base item animation layer, to create a child blueprint for your new item.
2. Assign item-specific animation assets (blend spaces, pose assets, aim offsets) to the exposed variables.
3. Call "Link Anim Class Layers" in your blueprint or gameplay ability to switch to the new animation set.
4. Validate transitions, inertial blending, and hand placement in-game.

Step 1: Create the Item Animation Layer Blueprint

1. In the Content Browser, locate ABP_ItemAnimLayersBase in /Plugins/MotionCore/EpicGames/Characters/Heroes/Mannequin/Animations/LinkedLayers inside Motion's plugin folder.
2. Create a child blueprint and rename the copy to match your item (for example, ABP_ShotgunAnimLayers).

Inherit, Don't Rebuild

The base class already contains locomotion graphs, additive pose logic, inertialization nodes, etc. Inheriting preserves these and keeps your changes focused on data overrides.

Step 2: Assign Item-Specific Anim Assets

Example

Motion ships with Lyra's animations for a pistol. You can use these to follow this guide if you do not have any fitting animations yet.

1. Open your new ABP_*AnimLayers blueprint.
2. In the Details panel, locate the exposed variables for the animations.

3. Point each variable to the correct animation sequence or blend space for your item.

Unsure which animation goes where?

Check MotionCore\EpicGames\Characters\Heroes\Mannequin\Animations\Locomotion\Unarmed\ABP_UnarmedAnimLayers if you are unsure which animation is plugged where. You can match the names with the pistol animations if you are using these. Otherwise check the animations and what they do, and match them with the animations you intend to use.

Step 3: Customize Per-Item Logic (Optional)

• Socket Adjustments: Update the weapon's hand sockets (weapon_l and weapon_r) or add socket offsets in your item implementation to offset grips.
• Unique State Machines: For radically different items (bows, shields, tools), implement (i.e. FullBody_Aiming) and / or extend the graph sections dedicated to aiming and additive layers.

Inertialization

Lyra's base blueprint already pipes each linked layer through Inertialization in the main animation blueprint. Keep that node in place so swapping items during equip montages remains smooth.

Step 4: Update Motion's Equip Logic

1. Locate the ability, component, or blueprint that equips the item (for example, your Gameplay Ability or weapon actor).
2. Set the linked anim layer class to your new ABP_*AnimLayers blueprint.

3. Ensure to play equip and unequip montages, so the new layer blends in during the transition.

No Item System

Motion does not ship with a solution for managing item state or an inventory. This means you will have to manage state of which item is being and spawn the skeletal mesh of the weapon yourself. Check Lyra's Inventory implementation for reference on how such a system could look like.

If this is something you are interested in seeing in Motion, please let me know via Discord.

Step 5: Test In-Game

1. Launch the project and equip the item using your Gameplay Ability or inventory system.
2. Watch the transition as the equip montage plays. Pose snapping indicates missing blend settings or incompatible poses.
3. Walk, sprint, jump, and crouch to confirm all locomotion states use the new animation assets.
4. Adjust sockets or additive poses if required.

Troubleshooting

• Animations Not Updating: Make sure the gameplay ability or item script triggers the layer swap when the item becomes active.
• Different Skeletons: Use Unreal's retargeting tools so your new animation assets match the character rig.