Cascade Combat System

Overview

Cascade Combat System is an action-combat framework for Unreal Engine 5 built on the Gameplay Ability System. It solves the problem of wiring together melee detection, combo sequencing, input buffering, targeting, weakspots, and hit reactions without rewriting GAS boilerplate for every project. You define UCascadeComboDefinition data assets in a node graph editor, attach UCascadeAbilitySystemComponent to your characters, and call InitializeCombat, the plugin handles input routing, window management, and networking from there.

Damage authoring lives on one structure: FCascadeDamageDescriptor. Each ability holds a BaseDamage descriptor (and an optional per-window override map) with the GE class, magnitude, hit tags, hit caps, weakspot resolution mode, and a project-extensible ProjectPayload (FInstancedStruct) where your game's faction / damage type / knockback / hit-stop fields live. The plugin reads only the universal fields; project listeners on OnPreHitResolve and OnHitDetected consume the rest.

Movement is fully decoupled. Plugin features (anim flying-mode, drag-target freeze, gravity GE, airborne tag, cancel-on-input, directional combos) call through ICascadeMovementBridge. A CMC-backed default ships with the plugin; projects on Mover, GMC, or custom systems supply their own bridge component. No coupling to a specific movement framework.

Getting Started

The fastest path to a working melee character is five steps. All of them can be done in Blueprint; C++ is only needed for Build.cs.

Combo Definition

UCascadeComboDefinition is a data asset that describes a complete combo: its unique tag, the node tree that drives sequencing, activation requirements, and timing. Create one per distinct combo in your Content Browser. The graph editor compiles the visual graph into the node tree at save time.

Combo Nodes

Each node in the combo graph is a UCascadeComboNode subclass. Nodes evaluate input, gate by conditions, and return the next node to execute. The graph editor represents these as connected boxes; the compiler converts them into the runtime node tree stored in the definition asset.

Runtime & Buffering

UCascadeAbilityTask_RunComboTree is the execution engine for a running combo. It is created internally by UCascadeCombo on activation; you interact with it through UCascadeAbilitySystemComponent rather than directly.

Runtime Builder

UCascadeRuntimeComboBuilder lets players customize and assemble combos at runtime, a skill-equip screen where the player picks which abilities fill each combo slot. Load a UCascadeComboTemplate data asset that defines the available slots and per-slot ability tag requirements, fill them via SetSlot, then call BuildCombo to produce a UCascadeComboDefinition that can be registered with the ASC.

// Build and register a player-assembled combo at runtime
Builder->LoadTemplate(MyComboTemplate);
Builder->SetSlot(0, UMyLightAttack::StaticClass());
Builder->SetSlot(1, UMyHeavyFinisher::StaticClass());

UCascadeComboDefinition* Built =
    Builder->BuildCombo(CascadeTags::Combo::Mixed::LLH, this);

if (Built)
{
    CascadeASC->RegisterCombo(Built);
}

Animation Abilities

UCascadeAnimAbility is the base class for montage-driven abilities. On activation it plays Montage at PlayRate, optionally jumping to MontageSectionName. When the montage completes or is cancelled, the ability ends automatically. UCascadeChargedAbility extends it with hold-to-charge mechanics, accumulates a 0–1 charge percentage between MinChargeTime and MaxChargeTime, fires OnChargeReleased on release.

Both classes are non-damaging by design. Damage is opt-in via composition, your project subclass holds a FCascadeDamageDescriptor BaseDamage field, implements ICascadeHitContextProvider::GetActiveDamageDescriptor, and spawns UCascadeAbilityTask_DamageHandler in the BP graph for per-hit reactions. See the Damage sections below.

Damage Descriptor

FCascadeDamageDescriptor is the single struct that carries an ability's damage authoring, what GE to apply, magnitude, semantic tags, hit caps, weakspot resolution, project-extensible payload. Abilities that want to deal damage implement ICascadeHitContextProvider::GetActiveDamageDescriptor(WindowTag) and return the descriptor for the active window. Hit producers (notify state, projectile, direct dispatch) call this at hit construction time and stamp the result into FCascadeHitData::SourceDescriptor.

// In your project's UEBAttackAbility
UPROPERTY(EditDefaultsOnly) FCascadeDamageDescriptor BaseDamage;
UPROPERTY(EditDefaultsOnly) TMap<FGameplayTag, FCascadeDamageDescriptor> WindowOverrides;

FCascadeDamageDescriptor GetActiveDamageDescriptor_Implementation(FGameplayTag InWindowTag) const override
{
    if (const FCascadeDamageDescriptor* Override = WindowOverrides.Find(InWindowTag))
    {
        return *Override;
    }
    return BaseDamage;
}

Damage Handler Task

UCascadeAbilityTask_DamageHandler is the single ability task damage-producing abilities spawn from their BP graph. One handler per ability, it listens for hits the ability produces (whether from a montage notify trace, a projectile collision, or a direct dispatch) and surfaces them as pins for designer-authored reactions. No timing parameters, animator owns timing, ability owns reactions.

// AOE shockwave at the impact frame of a slam montage
TArray<AActor*> Targets = UEBTargetingHelpers::GetEnemiesInCone(
    GetActorLocation(), GetActorForwardVector(), 600.f, 45.f, true);

DamageHandler->DispatchDirectHits(Targets, BaseDamage, EBTags::Window::Shockwave);

Resolution Pipeline

Every hit, trace, projectile, or direct dispatch, converges on the same two-phase pipeline on the attacker's ASC. Both delegates pass FCascadeHitData& by mutable reference so listeners can contribute resolution data.

The plugin's default damage applicator (UCascadeAbilitySystemComponent::HandleHitDetected) provides a working baseline, applies SourceDescriptor.DamageEffect with Magnitude as a SetByCaller. Projects bind their own listener for richer behaviour (faction filtering, damage-type resists, knockback application, status proc rolls, etc).

Passives

UCascadePassiveAbility is granted and activated automatically by the ASC during GrantCombatAbilities. It does not need an input binding and is never directly activated by the player. Use it for persistent effects, bleed-on-hit procs, damage auras, combo extension bonuses, that live as long as the character has the ability in their spec.

Add passive abilities to the PassiveAbilities array on your UCascadeCombatSetup asset to have them granted automatically on initialization.

Damage Window

UCascadeANS_DamageWindow is the AnimNotifyState that activates hit detection for the duration it is active in the montage. Place it on any frame range where an attack should connect. It polls socket positions each tick, performs swept-volume traces, and broadcasts FCascadeHitData for every new hit, automatically deduplicating within a single swing.

Combo Window

UCascadeANS_ComboWindow marks the frames inside a montage where the combo system accepts the next input. When the notify state begins, it signals the ASC to open the window and replay any buffered input. When it ends, the window closes.

Other Notifies

Cascade ships several additional notifies that cover common combat patterns without requiring custom ability code.

Weapons

ACascadeWeaponActor is the base class for any weapon that participates in Cascade hit detection. It implements ICascadeTraceConfigProvider so UCascadeANS_DamageWindow can read socket positions from the weapon mesh directly. Attach it to a character socket; call DrawWeapon() and SheathWeapon() to transition states, the weapon re-attaches to DrawnSocket or SheathSocket automatically.

// Get the currently drawn weapon on any actor
ACascadeWeaponActor* Weapon =
    ACascadeWeaponActor::FindDrawnWeapon(Character);

// Retrieve just the mesh for socket queries
UMeshComponent* Mesh =
    ACascadeWeaponActor::FindDrawnWeaponComponent(Character);

Projectiles

ACascadeProjectile is the base actor for ranged attacks. Spawn it from UCascadeAN_SpawnProjectile or from an ability directly. Call InitializeProjectile(CascadeASC, SourceAbility, HitTags) after spawning so the owning ASC receives FCascadeHitData on impact. Movement behavior is a swappable UCascadeProjectileMovementStrategy, set MovementStrategyClass on the projectile to choose one.

Targeting

The targeting system has two layers. UCascadeTargetingSubsystem is a world subsystem for soft-lock management, it scores candidates by angle and distance and can hold a locked target across frames. UCascadeTargetingQuery subclasses are GAS-integrated query objects used inside abilities to resolve target data for a single activation.

FVector GetTargetPoint_Implementation() override
{
    // Return the world position used for scoring (e.g. chest bone)
    return GetMesh()->GetSocketLocation(FName("spine_03"));
}

bool IsTargetable_Implementation() override
{
    return !IsDead();
}

Weakspots

Weakspots are shape components placed on the victim's mesh that contribute tags to hits that land inside them. Used for headshots, armor breaks, exposed cores on big enemies, and lock-on regions. The notify state's WeakspotResolution (on the descriptor) controls how overlapping matches are resolved.

Reactions

The reaction system decouples visual hit feedback from ability code. UCascadeReactionComponent lives on any actor that needs to respond to being hit or killed. It receives replicated hit and death triggers, evaluates a priority-sorted list of handlers from a UCascadeReactionSetup data asset, and executes the first handler whose tag conditions are met.

Movement Bridge

Cascade is movement-system-agnostic. Plugin features that need to read or manipulate the avatar's movement state, anim flying-mode toggle, drag-target freeze, gravity-scale GE, airborne tag, cancel-on-input, directional input adapter, call through ICascadeMovementBridge. Projects supply a bridge component implementing the interface; the ASC discovers it on InitAbilityActorInfo.

Input

Cascade routes all input through the ICascadeInputAdapter interface, decoupling the source of input from combo and ability execution. The default implementation is UCascadeEnhancedInputAdapter for players. For AI, use UCascadeAIInputAdapter. Implement the interface yourself to support any custom input source.

// Submit a combo input from an AI behavior tree task
UCascadeAIInputAdapter* Adapter = CascadeASC->GetAIInputAdapter();
Adapter->RequestComboInput(CascadeTags::Attack::Light, {});

// Activate a standalone ability directly
Adapter->RequestAbilityInput(SpecHandle);

Gameplay Tags

Cascade registers its tag namespace automatically. All native tags are declared in CascadeGameplayTags.h and accessible as CascadeTags:: in C++.

Debug Tools

Cascade includes debug utilities gated behind CVars and compile-time conditions. None require manual stripping for shipping builds.

Replication

Cascade is server-authoritative. All combat decisions, hit detection, combo progression, ability activation, happen on the server. Below is a summary of each system's replication model.