###### tags: `Combat`, `Documentation`

# Doc: Combat - Blocking/Parrying

## Introduction

Citadel has been moving away from the random roll shield blocking system where shields block x% of all hits via random rolls. Instead, we've moved our block-capable items for the most part towards being able to be used to actively defend, via blocking or parrying.

## In-game Stat viewing

When examining an item, if it is able to block/parry, you'll see something like this.
Click [Show Stats] to open a window that displays its capabilities and numbers. This includes explanations for what each stat does.

## Bindings

The default bindings for block/parry are `F` to block (hold it down!), and `G` to parry (press once to initiate sequence). You can rebind them as needed, including to a toggle instead of hold to block.

### A note on Independent Bindings

This is also said in the (upcoming) keybindings documentation, but it is highly recommended to bind block/parry hotkeys to independent binds while on hotkey mode. This means they will trigger the moment the key is pressed, rather than only when the exact key combination is pressed, meaning you will be able to block/parry even while holding down shift rather than having to manually bind block to both `key` and `Shift+Key`.

## Blocking

The first part of the new mitigation system is active blocking.
To use it, simply hold down the block keybind (or if you set the toggle keybind, press it down once), and you'll start to directionally block with the item.
- For QoL purposes, when blocking, the system will find an item to block with automatically if the currently held item is unable to be used to block
- Combat mode **must** be on to block, but the system will flick it on if it isn't on already. If combat mode is dropped during this time, blocking will end.
- Some certain things like the riot shield arm cybernetic implant will automatically toggle on when attempting to block if you are unable to otherwise find an item to block with.

### Visual Effects
While blocking, the user's entity is shifted towards the direction they're facing.

### Active Usage
While blocking, most items (see stats in the viewer) will drain **buffered stamina** per second. You don't want to keep it on for too long.
Most items also have a very short (0.05-0.5) second windup before the blocking is active.
Blocking is usually (see stats) **directional**, meaning you have to face the direction the attack is coming from for it to work.

### Damage mitigation

Blocking uses a "simple" damage mitigation formula that reads the stat numbers of the items to determine how much damage is blocked, in general. The code allows for overriding behaviors at every part of the block damage mitigation and some items may behave differently.

In general though, damage blocked is calculated using this formula:

Damage received = max(0, (damage limit - incoming damage)) + (incoming damage - damage absorption) * damage multiplier

- These variables can be overridden/different for different attack types. See the upcoming combat reference for documentation on how that works.

In layman's terms:
1. When an attack comes in, the damage is first checked against the **damage limit** of a blocking shield/item. If it's over that, anything over the limit is going to hit the user and not be blocked.
2. Any damage below the limit has the blocking item's **damage absorption** subtracted from it. This damage will not impact the user.
3. Any damage inbetween absorption and limit is multiplied by the **damage multiplier**. The result is going to hit the user.

Damage **blocked**, not received, is then turned into stamina damage, which usually is going to hit in a percentage-ratio between the user's arm that's holding the blocking item and their chest. This means with a high enough mitigating item, the user can still collapse from stamina exhaustion.

## Parrying

Active parrying is the counterpart to active blocking. Instead of being a held-down/maintained-per-second function, it's a single time-based parry sequence.

### Basics

Press the hotkey for initiating a parry sequence, and the system will look for something to parry with in this order:

1. The item held in hand
2. Martial arts parrying
3. Unarmed parrying if there's an empty hand available
4. Any other items it can find if none of the above are available.

- Combat mode needs to be on for parry to work. If combat mode is dropped, the parry sequence ends prematurely. Combat mode is automatically turned on if possible by the system for QoL purposes

This begins a timed (see stats of item) parry sequence consisting of a windup, active, and spindown.

### Visual Effects
Parrying has a telltale visual effect that shows during the windup, active, and spindown period.

### Timing
Every item that can parry has a specific "tick" in the active sequence marked as "perfect". Parry efficiency is set to the **perfect efficiency** on any hits parried on this tick, as well as on any ticks within the perfect **leniency threshold**.
Any hits that are outside are then penalized with a (currently only linear) formula for calculating falloff (see item stats) down from the **perfect efficiency**.

### Damage mitigation
In general, parrying blocks efficiency% of incoming damage.

### Penalties
Parries aren't free. Parrying in general will drain an amount of buffered stamina instantly (see item stats), but if you fail to connect a parry considered successful (for example, some items have harsh thresholds for something to be considered successful, up to 40-50% efficiency, while others just require any hit at all to connect during the window), you will be hit with various penalties depending on the item.
Examples: Staggered from sprinting for a while, prevented from attacking for a while, having a higher cooldown on your next parry.

### Cooldowns
Most parrying items respect click delay cooldown. Some have a "hard" cooldown meaning that even if you connect a successful parry they will still be unable to parry again until the cooldown is over and you are otherwise able to attack via click delay cooldown.

### Counterattacks
Parrying isn't just timed blocking. On hitting a successful parry, depending on the item, several "countereffects" may trigger.
For example, a successful parry with a captain's sabre automatically swings to attack the attacker with a full damage blow that does not take any stamina. Same for unarmed parrying in melee fistfights.
This generally depends on the item, but this can be extremely powerful in certain situations, for example, if 7 people are attacking you in melee and you parry perfectly you attack all 7 of them at once without any cooldown inflicted on yourself or stamina drained for the attack.

Parry counterattacks are unable to be blocked or otherwise intercepted by parries, to prevent potential infinite recursion leading to instant death.

Other supported (yet potentially unused) countereffects include:
- Staggering the attacker
- Disarming the attacker
- Stunning the attacker
- Knocking down the attacker
- Reflecting a projectile back at the attacker