Weapons · Updated May 20, 2026

System Link — Weapon Reload Pipeline

System Link — Weapon Reload Pipeline

⚠ NOT IMPLEMENTED — kept for reference only.
SystemLink does not have a reload mechanic and is not planning to add one. Confirmed by user 2026-05-20. The ammo model is a single pool per weapon: CurrentAmmo decrements on shot, refills via pickups. MaxAmmo is set high enough to make reload unnecessary (e.g. AR = 600, Shotgun = 60).
This doc was an early design exploration and is preserved only as a "what if we ever do" reference. Do not cite it for current behavior. The canonical ammo model is in Docs/WeaponActor.md and the design rationale is in project_design_vision.md memory.

#Overview

Reloading is a state-driven, animation-synchronized process that bridges:

  • GAS (state + gating)
  • WeaponsComponent (ammo + logic)
  • Animation (timing + visuals)

Unlike firing (instant) and equip (one-shot), reload is:

  • Time-based
  • Interruptible (optionally)
  • Animation-authoritative for timing

#Core Design Principles

#1. Reload Is Ability-Driven

Reload is implemented as a GAS ability:

USLGA_ReloadWeapon

Responsibilities:

  • Gate reload start
  • Apply reload state tag
  • Play reload montage
  • Coordinate timing via animation events

#2. Animation Drives Timing (NOT Code Delays)

Reload timing is NOT done with timers like:

❌ Delay(2.0)

Instead:

  • Anim notify defines when ammo is applied
  • Ability listens for that event

#3. Ammo Is Applied Mid-Animation

Critical rule:

  • Ammo is NOT applied at montage start
  • Ammo is applied at the exact animation frame

#Reload Flow

#Step 1 — Input

Input → Reload Ability

#Step 2 — Ability Activation

Checks:

  • Has reserve ammo
  • Magazine not full
  • Not equipping
  • Not already reloading

Applies tag:

SLTags.States.Weapon.Reloading

#Step 3 — Play Reload Montage

Played via:

ASC->PlayMontage(...)

Supports:

  • FP montage (local only)
  • TP montage (replicated)

#Step 4 — Wait for Reload Event

Ability listens for:

SLTags.Events.Weapon.Reload.Insert

Triggered via anim notify:

USLAnimNotify_SendGameplayEvent

#Step 5 — Apply Ammo

WeaponsComponent:

ApplyReload()

Typical logic:

  • Calculate missing ammo
  • Pull from reserve
  • Update CurrentAmmo
  • Update ReserveAmmo

#Step 6 — Montage Completion

Ability waits for:

  • OnCompleted OR
  • OnInterrupted

Then:

  • Removes reload tag
  • Ends ability

#Animation Structure

#Reload Montage Sections

Typical sections:

  • Start (raise weapon / eject mag)
  • Insert (magazine insert or shell load)
  • End (return to ready)

#Anim Notifies

Key notify:

Reload.Insert

Optional:

  • Reload.Start
  • Reload.End

#Reload Types

#1. Magazine Reload (Standard)

  • Single ammo update
  • One notify (Insert)

#2. Incremental Reload (Shotgun Style)

Loop:

  • Insert shell → notify
  • Apply +1 ammo
  • Repeat

Ability structure:

  • Loop montage section
  • Exit when full or canceled

#3. Full Replace Reload

  • Ammo set instantly at notify
  • Used for energy weapons

#First-Person vs Third-Person

#First-Person

  • Full animation detail
  • High fidelity hand movement
  • Local-only montage

#Third-Person

  • Simplified animation
  • Replicated montage
  • Focus on readability

#Animation Layering

Reload typically uses:

  • Full-body montage (can override upper body)
  • OR layered montage (preferred)
  • Upper-body slot (reload slot)
  • Preserve locomotion
  • Blend with movement

#Interrupt Handling

Reload can be:

#Non-Interruptible

  • Must complete once started

Interrupt conditions:

  • Fire input
  • Weapon switch
  • Sprint

#Interrupt Flow

On interrupt:

  • Stop montage
  • Do NOT apply ammo (if not yet applied)
  • Clear reload tag

#Networking Model

#Client

  • Starts reload immediately
  • Plays FP montage
  • Sends ability activation to server

#Server

  • Confirms reload
  • Plays authoritative montage (TP)
  • Applies ammo on notify

#Remote Clients

  • Receive montage replication
  • See reload animation only

#Edge Cases

#Empty Reload

  • Plays different montage (optional)
  • Same notify timing

#Partial Reload

  • Stops early if:
    • Ammo full
    • Player cancels

#Reload While Moving

  • Allowed via upper-body slot
  • Movement continues

#Reload While ADS

Options:

  • Exit ADS automatically
  • Blend reload into ADS (advanced)

#Integration With Other Systems

#Equip System

Reload is blocked when:

State.Weapon.Equipping is active

#Firing System

Firing is blocked when:

State.Weapon.Reloading is active

#Ammo System

Uses:

  • CurrentAmmo
  • ReserveAmmo
  • AmmoPerReload (optional)

#System Flow Summary

Input ↓ GAS Reload Ability (Gate + State) ↓ Play Montage (ASC) ↓ Anim Notify (Insert) ↓ WeaponsComponent::ApplyReload() ↓ Montage Complete / Interrupt ↓ Clear Reload State

#Key Benefits

  • Frame-perfect ammo timing
  • Fully network-safe
  • Animation-driven feel
  • Supports multiple reload styles
  • Clean integration with GAS

#Common Pitfalls

#❌ Using delays instead of notifies

→ Causes desync

#❌ Applying ammo at montage start

→ Breaks animation realism

#❌ Not handling interrupts

→ Leads to stuck states

#❌ Mixing FP/TP logic

→ Causes replication bugs

#Future Extensions

  • Tactical reload vs empty reload
  • Reload speed modifiers
  • Per-shell reload cancel windows
  • Animation-driven sound sync
  • Dual-magazine systems