Melee

Module PulseCombatMelee (depends on PulseCombat). A melee attack is a gameplay ability that plays a combo of steps. Every step has its own damage, hit shape and timing, and works with or without animation, so a prototype can fight before any montage exists.

Setup

  1. Make the attacker a combatant (ability system, UPulseHealthAttributeSet, UPulseCombatComponent, see Combat).
  2. Create a Pulse Attack data asset (UPulseAttackDefinition, Primary Asset Type PulseAttack) with the steps of the combo.
  3. Give the ability UPulseMeleeAttackAbility (or a Blueprint child) with the attack definition as source object of the spec, or set Attack on the ability. Without both, the ability plays InlineSteps (default: three hits with 10, 12 and 18 damage and timed windows).
  4. Bind the attack input to the ability (input ID or your own input code calling Press Attack). Pressing again during a combo continues it; the ability handles the input itself.
FGameplayAbilitySpec spec(UPulseMeleeAttackAbility::StaticClass(), 1, INDEX_NONE, SwordAttack);
AbilitySystem->GiveAbility(spec);

Steps

Field Meaning
Montage, MontageSection, PlayRate Optional animation. Without montage the step lasts Duration.
bUseTimedWindows Use the times below even with a montage (ignore the notify states).
Damage, DamageType, DamageTags, bCanCrit, DamageEffect Damage spec of a hit. Pulse.Combat.Damage.Melee and the definition’s DamageTags are always added.
Shape Where the step hits (below).
HitEffects What a hit does after the damage (below).
Duration, HitWindowStart/End, ComboWindowStart/End Timing in seconds when no montage drives it.

InputBuffer of the definition: input up to this many seconds before the combo window opens is remembered.

Timing from animation

With a montage, place the anim notify states Pulse Melee Hit Window (the hit check runs while it is active) and Pulse Combo Window (input continues the combo) on the montage. The montage end finishes the step.

Hit shapes

Type Use
Sphere, Capsule, Box A shape at Offset / Rotation relative to the attacker (X = forward). Good for fists, claws, area swings and any pawn without weapon sockets.
Sockets A sphere of Radius swept from the last to the current position of the two sockets StartSocket / EndSocket of the component tagged ComponentTag (on the attacker or an attached actor, e.g. the weapon). Fast swings are split into several sweeps (MaxSweepStep on the ability). The weapon actor becomes the damage causer.

The hit check runs on the authority every HitCheckInterval seconds while the hit window is open. Every target is hit at most once per step. By default only enemies are hit (bOnlyHostile, the hostility rule of the combat settings), except targets whose IPulseDamageable::IsHitByAnyAttacker returns true (resource nodes); more filters go into HitFilters. The hit check looks for the object types in HitObjectTypes (default Pawn and PhysicsBody).

Attack timeline

Pulse::Combat::Melee::BuildAttackTimeline (Melee/PulseAttackTimeline.h) describes an attack definition (or a list of steps and an input buffer) as a timeline, without a world, for editors and tests. It reads the same data as the ability, there is no extra format:

  • Every step gets its Duration (without montage Duration, otherwise the montage at PlayRate times the rate scale of the montage, from its section along the linked next sections, up to where the montage starts to blend out: the ability leaves the step there) and its windows in seconds since the step started: Hit, Buffer (input is remembered; with montage notify states every input before the combo window, and without a combo window in the step every input, so the step continues at its end), Combo (the cancel window: input starts the next step at once) and Recovery (from the end of the last hit window to the end of the step). Windows come from the times of the step, or from the notify states of the montage when it drives the step, and are cut to the step.
  • The steps are placed in the fastest chain: the next step starts when the combo window opens, at the latest when the step ends (StartInAttack, EarliestNext). A step no input can leave ends the chain; the steps after it are listed with bReachable false. Duration of the timeline ends with the last reachable step.

BuildStepTimeline(Step, InputBuffer, bHasNextStep) gives one step. The last step has no buffer and no combo window, as the ability ignores input there. Only notify states on the montage itself count, not those of the animations inside it. A section that links back to one already played (a loop) is shown once.

Attacks in the editor

Attack definitions open in the config workshop of the Pulse Editor Kit (tree, details, validation, notes) with the preview Attack of PulseGameplay on the right:

  • Timeline: a row per step from BuildAttackTimeline, placed in the fastest chain, with a ruler in seconds. The step bar shows how long the step lasts without input; above it the Hit window, the input Buffer and the cancel (Combo) window, and Recovery below. A bright mark (Next step in the legend) shows where the next step starts at the earliest. The legend stays on one row at the docked width; each chip has the long name as its tooltip. Steps no input can reach are faint and marked “unreachable”.
  • Damage: a button per step picks the step the damage calculator uses (damage, type, crit and tags of the step, Pulse.Combat.Damage.Melee and the tags of the definition, as the ability builds them). See Damage calculator in the editor.
  • Where used: abilities, weapons and other assets that name the attack, with a button that opens them.

Steps in the tree and on their cards are named by their place in the attack, “Step 1”, with the montage section (“Step 2: Slash”) or else the montage when the step has one. Every step card carries its own small timeline (hit, buffer and cancel lanes) and the summary “10 damage · hit 0.15-0.30 s” (its tooltip shows the whole summary); the tree lines add the cancel window and the length of the step.

Hit effects and filters

Both are instanced structs from PulseCombat and are shared with ranged attacks:

Hit effect (FPulseHitEffect) Does
FPulseHitEffect_Knockback Launches characters (or pushes simulated bodies) away from the attacker
FPulseHitEffect_ApplyEffect Applies a gameplay effect to the target (poison, slow, stagger)
FPulseHitEffect_SendEvent Sends a gameplay event to target and/or attacker
FPulseHitEffect_GameplayCue Executes a gameplay cue at the hit (sparks, sound)

bOnlyIfDamaged (default on) skips the effect when the target was immune or blocked everything. FPulseHitFilter_TargetTags accepts only targets whose tags match a query. Write your own by deriving from FPulseHitEffect::Apply(const FPulseHitContext&) or FPulseHitFilter::Accepts.

Events

  • On Melee Hit (dynamic) / OnMeleeHitNative on the ability, and the Blueprint hooks On Hit and On Step Started.
  • The attacker gets the gameplay event Pulse.Combat.Event.AttackHit for every hit (e.g. to refund stamina).
  • The damage itself goes through the normal pipeline: On Damaged of the target’s combat component, messages.

While the ability runs the attacker has Pulse.Combat.State.Attacking; it is blocked by Dead and Staggered, so a stagger interrupts a combo. Cooldowns are ordinary GAS cooldown effects on the ability. Costs are AttackCosts (Pulse costs, FPulseCostList, see Combat and inventory): stamina is an Attribute cost (FPulseCost_Attribute of Pulse Foundation, Attribute = Pulse.Stat.Stamina), which works with the stamina set of the ability system and with the Pulse Attributes component alike; items are an Items cost. A GAS cost effect on the ability still works, but only for attributes of the ability system. When a Pulse cost cannot be paid the ability does not start and reports the cost failure tag of GAS (ActivateFailCostTag), like a cost effect. When the server cannot pay after the check passed (two costs that each see the same stamina or items, the second payment fails and is rolled back), CommitAbility fails as well: the attack ends cancelled without a hit and the GAS cost effect is not applied.

Magnetism and targets

When a step starts the attacker turns towards the attack target if it is within MagnetismRange and MagnetismAngle (bUseMagnetism). The target is, in this order: the Target of the activation event data, the lock-on target, the soft target of UPulseTargetingComponent (Pulse::Combat::FindAttackTarget).

AI and scripts

An AI needs no player input: activate the ability on the server and pass the target in the event data.

FGameplayEventData data;
data.Target = Enemy;
Pulse::Combat::PressAbilityInput(AbilitySystem, UPulseMeleeAttackAbility::StaticClass(), &data);

PressAbilityInput (Blueprint Press Attack) activates the ability when it is not running and otherwise presses its input, so calling it again continues the combo. It works for server controlled pawns; a player’s ability is predicted on the client and must be pressed there.

Multiplayer

The ability is local predicted: the owning client plays the montage at once, the server runs the hit check and deals the damage. Combo input reaches the server through the replicated input events of the ability.

Cheats

Command Does
PulseCombatGiveMelee [asset path] Gives the melee ability (inline combo without a path)
PulseCombatAttack [combo\|server] Presses the attack; combo presses three times in the combo windows

PulseGameplay plugin documentation.

This site uses Just the Docs, a documentation theme for Jekyll.