Weapons · Updated Apr 10, 2026

System Link — Weapon Animation Architecture

System Link — Weapon Animation Architecture

#Overview

The System Link weapon animation system is designed with a strict separation of responsibilities between gameplay logic, presentation, and animation execution.

The system is built around:

  • Gameplay Ability System (GAS) → controls when actions occur
  • Weapons Component → controls what is equipped and state transitions
  • View Drivers (FP/TP) → control how weapons are visually presented
  • Animation Blueprints (FP/TP) → control how the weapon animates

#Core Design Principles

#1. Weapons Are Not Abilities

Weapons are implemented as components (USLWeaponsComponent), not as GAS abilities.

  • GAS abilities only gate actions (equip, fire, reload)
  • Weapon logic (spread, ammo, etc.) lives in the weapon component

#2. Animation Is Data-Driven

Each weapon defines its animation behavior via:

USLWeaponDataAsset

Including:

  • Skeletal meshes (FP / TP)
  • Attach socket names
  • Equip montages
  • Animation layer class
  • IK socket configuration

#3. Layered Animation (Not Full AnimBP Swapping)

Instead of swapping entire animation blueprints:

LinkAnimClassLayers(WeaponData.AnimLayerClass)

This allows:

  • Per-weapon animation customization
  • Shared base locomotion
  • Clean separation of weapon-specific logic

#Equip Animation Flow

#Step 1 — Input

Input → WeaponsComponent::RequestEquip()

  • Sends gameplay event:

    • SLTags.Events.Weapon.Equip

#Step 2 — Ability Activation

USLGA_EquipWeapon (LocalPredicted)

  • Adds tag:

    • SLTags.States.Weapon.Equipping

  • Prevents re-entry

#Step 3 — Prepare Equip

WeaponsComponent->PrepareEquip(WeaponData);

Responsibilities:

  • Set weapon meshes (FP / TP)
  • Cache socket names
  • DO NOT attach yet
  • DO NOT finalize animation layers yet

#Step 4 — Play Equip Montage

Montage is played using:

ASC->PlayMontage(...)

Important:

  • Do NOT play montages directly on mesh
  • GAS handles:
    • prediction
    • replication
    • synchronization

#Step 5 — Anim Notify → Gameplay Event

Custom notify:

USLAnimNotify_SendGameplayEvent

Fires:

SLTags.Events.Weapon.Equip.Attach

#Step 6 — Wait for Event

Ability uses:

UAbilityTask_WaitGameplayEvent

When event is received:

WeaponsComponent->FinalizeEquip();

#Step 7 — Finalize Equip

Responsibilities:

  • Attach weapon to character socket
  • Link animation layers
  • Enable IK
  • Clear pending weapon state

#Step 8 — Completion Gate

Equip completes only when:

TPComplete && FPComplete

With:

FPComplete = !IsLocallyControlled()

This ensures:

  • Remote players only require TP montage
  • Local player requires both FP + TP

#Animation Blueprint Architecture

#Third-Person AnimBP (Source of Truth)

  • Full body animation
  • Locomotion
  • Base weapon pose

#First-Person AnimBP (Derived)

Uses:

Copy Pose From Mesh (TP)

Then layers:

  • Recoil
  • Weapon sway
  • ADS offsets
  • IK adjustments

#Animation Layers

Weapon-specific animation is injected via layers:

  • WeaponPose
  • WeaponAdditives
  • WeaponIK
  • WeaponADS (optional)

Defined per weapon via:

AnimLayerClass

#Left-Hand IK System

#Implementation

  • Solver: FABRIK
  • Effector source: weapon socket
  • Space: Bone Space of right hand

#Core Calculation

Effector_BS = HandR_WS.InverseTransformPosition(Socket_WS)

#Result

  • Stable left-hand placement
  • No drift
  • Consistent FP/TP alignment

#First-Person vs Third-Person Behavior

FeatureFirst PersonThird Person
VisibilityOnlyOwnerSeeOwnerNoSee
MontageLocalReplicated
IK PrecisionHighMedium
Weapon SwayEnabledMinimal

#View Driver Responsibilities

Each view (FP / TP) has a driver:

  • FSLWeaponViewDriverBase
  • FSLWeaponViewDriverFP
  • FSLWeaponViewDriverTP

Responsibilities:

  • Initialize meshes
  • Equip / Unequip presentation
  • Handle animation layer linking
  • Compute IK targets
  • Skip execution on dedicated server

#Dedicated Server Behavior

Presentation is disabled:

ShouldRunPresentation() == false

Ensures:

  • No animation work on server
  • Reduced overhead

#System Flow Summary

Ability (WHEN) ↓ WeaponsComponent (WHAT) ↓ ViewDriver (WHERE / WHICH VIEW) ↓ AnimBP (HOW)

#Key Benefits

  • Clean separation of concerns
  • Fully network-compatible (prediction + replication)
  • Data-driven weapon animation
  • Reusable animation system
  • Scalable for multiple weapons

#Future Extensions

Planned areas for expansion:

  • Reload animation integration
  • Fire animation layering
  • Additive recoil stacking
  • Multi-weapon switching support
  • Animation-driven weapon states (ADS, sprint, etc.)