Input

Documentation Unreal Engine Player Combat Input

Input turns a key into an input tag that the action graph or an ability answers. An item brings its keys while drawn and takes them back when put away; two buttons together can send a chord.

Make a key play a move

3 minutes
  1. 1

    Make the input

    From the Content Browser's Input menu, create an Input Action, IA_LightAttack, and an Input Mapping Context, IMC_MySword, that maps a key to it.
  2. 2

    Point the item at the context

    Make Item_MySword first (Items). On its Item Definition, set the Equippable fragment's Input Mapping Context to IMC_MySword, in place of the demo's IMC_UPC_Sword.
  3. 3

    Fill in the mappings

    Press Populate Input Mappings from IMC in the item's Equippable Designer Tools: it adds a row for IA_LightAttack sending UPC.Input.LightAttack.
    Item_MySword
    ▾Input Mappings [0]
    Input Action
    None▾
    Input Tag 
  4. 4

    Press the key

    Give the item an Action Graph with a transition from Root on UPC.Input.LightAttack, such as AG_MyFirstGraph from the Action Graph quick start. Set your item as the Default Item on a character's Equipment Manager so it is in hand at Play, and press the key.

Inputs an item brings

Details
Item_MySword
Equippable Designer Tools
Input Mappings
Populate Input Mappings from IMCSync Input Mappings from IMCValidate Input Mappings
Equippable
Input Mapping Context
IMC_MySword
Input Mapping Priority
0
Input Mappings
2 Array elements
Input Chords
0 Array elements
Equippable Designer Tools shows while the item's own Fragments carry an Equippable. Validate reports in the Universal Player Combat message log.
SettingDoes
Input Mapping ContextAdded to the player while the item is drawn.
Input Mapping PriorityHigher wins a key conflict; 0 by default. A combat style's context goes on at 10.
Input MappingsOne row per Input Action and the Input Tag it sends.
Input ChordsChords, live while the item is drawn.
Populate Input Mappings from IMC adds a row for each Input Action the list lacks and suggests its tag (the name with IA_ swapped for UPC.Input., when that tag exists). Sync also removes rows whose action the context lacks.

Keys that work whatever the character holds

Such a key goes in one of two places:
  • A graph move: a row in Input Mappings on the character's UPC Input Mapping component, which the character base creates and binds itself (leave Auto Bind off there; a pawn outside the character base ticks it). A row's Required State Tags, under its advanced arrow, let it fire only while the character carries all of them.
  • A gameplay ability: a row in the character's Starting Ability Set (below).
Either way, the Input Action needs a key in a mapping context the player already has (IMC_UPC_Default in the demo).
Details
InputMappingComponent
UPC
Input Mapping
Input Mappings
0 Array elements
Input Chords
1 Array element
Light + Heavy
Member Tags
2 Gameplay Tags
UPC.Input.LightAttack
UPC.Input.HeavyAttack
Output Tag
UPC.Input.Special
Priority
0
Display Name
Light + Heavy
Chord Window Seconds
0.08
Auto Bind
Created by the character base. Its Input Chords work whatever the character holds, beside the chords a drawn item brings.

Abilities that answer a key

A gameplay ability answers a key through an Ability Set row (UPC > Actions > Ability Set) naming the ability, its Input Tag and its Input Action. The character base's Starting Ability Set binds its rows' keys, and an item's Ability Sets to Grant bind theirs while it is drawn; a set granted any other way binds no keys.
Details
AbilitySet_MyCharacter
Abilities
Granted Gameplay Abilities
1 Array element
GA_Dodge
Ability
GA_Dodge
Ability Level
1
Input Tag
UPC.Input.Dodge
Input Action
IA_Dodge
Interrupts Action Graph
Forward Input While Active
Effects
Granted Gameplay Effects
0 Array elements
GA_Dodge stands for a dodge ability of your own. Interrupts Action Graph makes it the way out of any move.
SettingDoes
Input TagActivates the ability. Empty grants it with no input.
Input ActionBinds this Input Action to the Input Tag, in place of an Input Mappings row.
Interrupts Action GraphOff by default. The ability cuts the running move back to Root as it starts; a press its cooldown or cost refuses cuts nothing.
Forward Input While ActiveOff by default. Presses and releases go into the running ability, which hears them through its Wait Input Press and Wait Input Release tasks, for a hold or a charge. Leave it off for a toggle such as lock-on, whose second press clears the lock.
When a graph move and an ability share a tag, the graph asks first. Take a Dodge transition from Root on UPC.Input.Dash and an ability on the same tag:
  • The current move has a transition on that tag, its Required Tags and Blocked Tags pass, but its Conditions fail (a Vital Threshold needing 25 stamina, with 10 left): the press drops, and the ability never hears it.
  • The transition's Required Tags or Blocked Tags fail (it requires a tag of your own such as MyGame.Dodge.Unlocked, which the character lacks): the graph passes, and the ability answers.
  • The current move has no transition on that tag, such as a press during an attack with no dash transition of its own: the ability starts, and with Interrupts Action Graph ticked it cuts the attack first.
  • An ability sits on that tag but its cooldown runs, its cost cannot be paid or it fails to start: the press ends there, and the graph's fallback below does not run.
  • No ability sits on that tag: the graph's own fallback runs. At Root the press drops. During a move that Can be Cancelled by this input, the move is cut and the press runs again from Root. A press only Root has a transition for waits and runs from Root when the move ends, unless the move's action window opens first (Action Graph, Held Input Restart Window). Anything else drops.

Press two buttons together

A chord turns inputs pressed together into one tag, such as light and heavy attack sending UPC.Input.Special; each alone keeps its move.
SettingDoes
Member TagsTwo or more input tags, matched exactly.
Output TagSent once when every member lands in time.
PriorityThe highest wins when one press completes several chords, so a drawn shield can take over the sword's combination.
Put chords on the component's Input Chords, or on an item's Equippable fragment. Chord Window Seconds (0.08) is how far apart the member presses may land, in either order; a member press waits that long, so each button alone fires late. 0 turns chords off.

Pause combat input

Set Input Suspended on the UPC Input Mapping component stops presses for a cutscene or a menu; releases still pass, so a held block can end, and drawing and stowing still work. Is Input Suspended reads it. To shut the graph from gameplay, such as a stagger, use Global Block Tags.

The input tags that ship

Tags of your own work too.
TagFor
UPC.Input.LightAttack, UPC.Input.HeavyAttackLight and heavy attacks.
UPC.Input.GuardThe guard: block, parry and guard counter on one input.
UPC.Input.Dodge, UPC.Input.DashA dodge, a dash.
UPC.Input.SpecialA signature move.
UPC.Input.ExecuteAn execution or finisher.
UPC.Input.LockOnEngaging, switching or releasing a lock.
UPC.Input.Aim, UPC.Input.FireAiming and firing a ranged weapon.
UPC.Input.SprintSprinting while held.
UPC.Input.DropDropping the held item.
UPC.Input.Interact, .Secondary, .Tertiary, .QuaternaryUp to four interaction buttons.

Debug it

Log LogUPCInput Verbose logs each routed input: Input Action, tag, moment and outcome. The component's On Input Processed fires with the same answer, for a widget.
AdvancedHow a press reaches a move
The component turns a press into its tag, and the tag takes this walk:
A press enters at the topThe first stop that claims it ends the walk
1
Chords
Input Chords, Chord Window Seconds
A press of a chord member waits up to Chord Window Seconds for the other members. All of them in time sends the chord's Output Tag once, in place of the single presses; otherwise each press goes on by itself, in the order pressed. An input in no chord goes on at once.
2
Required State Tags
Input Mappings, an entry's Required State Tags
An entry with Required State Tags passes only while the character carries every one of them. Otherwise the input stops here, with no warning.
3
The action graph
a transition on the node the character stands on
When the current node has a transition for this tag and this moment (pressed, released, released early), the graph takes the input. Only the transition's tag gates count here, so the graph keeps the input even when that transition's conditions fail.
4
A granted ability
an Ability Set row's Input Tag
Otherwise an ability granted with this Input Tag answers. A cooldown or a cost that refuses it ends the press here. With Interrupts Action Graph ticked, the running move is cut back to Root before the ability starts.
5
The graph's fallback
Root's transitions and the node's cancel rules
Nothing claimed the input, so the graph gets it anyway. At Root it drops. During a move that this input may cancel, the move is cut and the input runs again from Root. A press that only Root has a transition for waits in the buffer and runs from Root when the move ends, unless the move's action window opens first, which drops it. Anything else drops.
Releases take the same walk: a transition on Input Released takes one, otherwise a granted ability on the tag hears it when it closes a real press, and anything else drops. Every routed input then fires On Input Processed with what it did.
  • An Input Action sends three moments a transition's Fires On picks from: Input Pressed as its triggers fire, Input Released when let go after that, Input Released Early when a hold is let go before it finishes.
  • On Input Processed skips a press Required State Tags or Set Input Suspended dropped, and reports a chord once it resolves, under its Output Tag and Display Name.
  • Two chords of one priority completing on one press warn; give them different priorities. Enhanced Input's chorded trigger works beside chords, without the window or the either-order press.
  • UPC.Ability.InterruptsActionGraph or UPC.Ability.ForwardInputWhileActive in an ability's Asset Tags sets that checkbox for every grant of it; the UPC Sprint Ability carries the second.
  • Auto Bind (off) binds the component's own Input Mappings with no Bind Inputs call, for a pawn not built on the character base or a player controller carrying the component. The character base binds them itself; an AI pawn binds none.
AdvancedTags, taps and holds
  • The tags in one go: right-click Input Mapping Contexts, Universal Player Combat > Generate Gameplay Tags from Input Actions. It makes a tag per Input Action from Tag Prefix (UPC.Input., so Populate suggests them) and the name less Input Action Strip Prefix, adds the missing ones to Tag Source Name with an optional Tag Comment, and reports counts.
  • A tap and a hold on one button: two Input Actions on one key, one with a Tap trigger sending UPC.Input.LightAttack, one with a Hold trigger sending UPC.Input.HeavyAttack. A trigger works on the Input Action or on its entry in the context.
AdvancedLists for prompts and rebinding
Get Active Input Mappings returns every live mapping: drawn items' and ability sets', newest first, then the component's own. Get Input Actions for Tag returns the actions sending one tag in that order, the first being the one a prompt shows.
Trigger Input sends a tag through the routing a press takes, for an AI, a UI button or a script, skipping chords, Required State Tags and Set Input Suspended. Forward Input Event to Granted Ability sends a press or release into a running granted ability.
The demo
  • Each demo weapon brings its own context (IMC_UPC_Sword, IMC_UPC_Shield, IMC_UPC_TwoHanded, IMC_UPC_Unarmed); the controller adds IMC_UPC_Default.
  • AbilitySet_UPC_Default binds lock-on, both interact keys, sprint and drop, and the guard key again to UPC.Input.GuardHeld for GA_UPC_GuardReturn, which runs while the key is down.
MultiplayerWhat runs where
Input is local: keys become tags and chords resolve on the machine controlling the player, before the action graph predicts anything, so Set Input Suspended needs no replication. An item's mappings and context, and an Ability Set's keys, register on the locally controlled player only.
The server grants abilities. Interrupts Action Graph cuts the player's own node at once and the server's copy when the activation arrives, outside the node's cancel rules. Forward Input While Active reaches the server through the stock Wait Input tasks, so it serves Local Predicted and Local Only abilities; a Server Initiated ability's server task misses a press made only on the client.
C++C++
  • UUPCInputMappingComponent binds Started, Triggered, Completed and Canceled per mapping: Triggered sends Input Pressed once per press, Completed Input Released, Canceled Input Released Early. BindInputs binds its own list; RegisterMappings and UnregisterMappings add and remove an item's, matched by Input Action, Input Tag and Required State Tags, one binding per entry, so two items registering one mapping each own one. RegisterChords and UnregisterChords do the same for chords.
  • UUPCInputMappingComponent::FindFor(Pawn) (Find Input Mapping For Pawn) returns the pawn's component, else its controller's.
  • Code calling UUPCActionGraphComponent::ProcessActionInput directly gets no chords, ability routing or suspension; Global Block Tags still apply.
  • An Ability Set stamps each row's Input Tag on the spec's dynamic source tags; UUPCAbilitySet::FindGrantedAbilityForInputTag finds it by exact match, the first activatable spec winning.
AdvancedTroubleshooting
A key that does nothing
  • The tags differ. The mapping's and the transition's Input Tag must match exactly; a parent tag fails.
  • The item is not drawn. Its mappings apply only while it is drawn.
  • No context maps the key. Validate Input Mappings reports a row whose action the item's context lacks.
  • A transition on the tag takes it, so an ability on that tag does not hear it (Abilities that answer a key).
  • The Output Log names the gap: a component with no Action Graph component, a row with no action or tag, an input component that is not Enhanced Input.