Add information on the damage pipeline rework (#42)

content/news/21.0release.md

@@ -91,6 +91,39 @@ The entries specified in the file consist of the target enum, the field name, th
 ```
 See the [documentation](https://docs.neoforged.net/docs/advanced/extensibleenums) for further information on how to use the new system and the [FML PR](https://github.com/neoforged/FancyModLoader/pull/148) for further details on the motivations of this change.
 
+## Damage Pipeline rework (introduced in NeoForge 21.0.31-beta)
+In NeoForge `21.0.31-beta`, damage events have been reworked.  
+The motivation behind this change was that the previous poorly named and documented events were causing constant confusion, especially among beginners. 
+
+### `DamageContainer`
+`DamageContainer` is a new class exposed via the damage events. This object allows modifications to all aspects of the damage pipeline, including absorption and invulnerability ticks.  
+You can modify the different types of reduction (`ARMOR`, `ENCHANTMENTS`, `MOB_EFFECTS` and `ABSORPTION`) through `addModifier`:
+```java
+// Reduce armor reduction by 1 hear
+container.addModifier(DamageContainer.Reduction.ARMOR, (container, currentReduction) -> Math.max(0, currentReduction - 1));
+```
+
+### `EntityInvulnerabilityCheckEvent`
+This new event represents the earliest point modders can use to cancel damage, and can be used to override entities that would otherwise be invulnerable in vanilla.  
+This event will always be fired when an entity is attacked, even if the attack would not actually damage the entity.
+
+### `LivingIncomingDamageEvent` (formerly `LivingAttackEvent`)
+This is the first event of the damage pipeline. Most modifications to the incoming damage should happen during this event.
+
+### `LivingShieldBlockEvent` (formerly `ShieldBlockEvent`)
+This event can be used to decide whether the entity is actually blocking the damage through the shield, and if so, how much of the damage is blocked.
+
+### `LivingDamageEvent.Pre` (formerly `LivingDamageEvent`)
+This event is the lastest point at which the final damage may be modified, or reduced to 0. However, the event is not cancellable as by when it is fired, armor and shield durability loses have already occurred.
+
+### `LivingDamageEvent.Post` (formerly `LivingHurtEvent`)
+This is the last event of the damage pipeline. It indicates that all damage has been applied to the entity, and can only be used for reacting to the damage being applied (i.e. to reduce custom hunger or thirst values).
+
+### `ILivingEntityExtension#onDamageTaken`
+This method has been added to living entities in order to allow them to react to *already applied* damage, without needing to override `actuallyHurt` and call super.
+
+We would like to thank [Caltinor](https://github.com/Caltinor) for their work on the [Pull Request](https://github.com/neoforged/NeoForge/pull/792), which you can consult for more information.
+
 ## Experimental Gradle Plugin
 We're currently developing a new experimental Gradle Plugin, focused on simpler buildscripts and improved caching. You can find information on its usage [here](https://github.com/NeoForged/ModDevGradle), and support is provided in the [thread](https://discord.com/channels/313125603924639766/1239579489617580072) on our [Discord server](https://discord.neoforged.net).