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.

Motion builds on Lyra's animation layer structure. Each holdable item can have its own locomotion poses and aim offsets while reusing shared logic from ABP_ItemAnimLayersBase.

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 Content/EpicGames/Characters/Heroes/Mannequin/Animations/LinkedLayers.
2. Create a child blueprint and rename the copy to match your item (for example, ABP_ShotgunAnimLayers).

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

Step 2: Assign Item-Specific Anim Assets

Motion ships with Lyra's pistol animations as a reference. Use these to follow this guide if you don't have fitting animations yet.

1. Open your new ABP_*AnimLayers blueprint.
2. In the Details panel, locate the exposed variables for animations.
3. Point each variable to the correct animation sequence or blend space for your item.

If unsure which animation goes where, check ABP_UnarmedAnimLayers in Plugins/MotionCore Content/EpicGames/Characters/Heroes/Mannequin/Animations/Locomotion/Unarmed/. Match the variable names with the pistol animations or examine what each animation does.

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.

Lyra's base blueprint 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. Play equip and unequip montages so the new layer blends in during the transition.

No Item System

Motion does not ship with item state management or inventory. You must manage which item is equipped and spawn the weapon mesh yourself. See Lyra's Inventory implementation for reference.

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.