Terasology · jdrueckert · Jun 30, 2023 · Apr 22, 2023 · Apr 22, 2023 · Apr 24, 2023
diff --git a/docs/_media/damage-overlay.jpg b/docs/_media/damage-overlay.jpg
diff --git a/docs/_media/directional-damage-overlay.jpg b/docs/_media/directional-damage-overlay.jpg
diff --git a/docs/_media/hud.jpg b/docs/_media/hud.jpg
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,10 +1,12 @@
 * [Home](README.md)
-* Events
+* Players
+  * [Health HUD](ui-hud.md)
+  * [Damage Overlay](ui-damage-overlay.md)
+* Modders
+  * [Health](health.md)
+  * [Damage](damage.md)
   * [Regeneration](regeneration.md)
   * [Restoration](restoration.md)
-* Systems
-  * [Damage System](system-damage.md)
-  * [Block Damage System](system-block-damage.md)
-* API
+* Developers
   * [API](http://jenkins.terasology.io/teraorg/job/Terasology/job/Modules/job/H/job/Health/job/master/javadoc/overview-summary.html)
   * [API (SNAPSHOT)](http://jenkins.terasology.io/teraorg/job/Terasology/job/Modules/job/H/job/Health/job/develop/javadoc/overview-summary.html)
diff --git a/docs/damage.md b/docs/damage.md
@@ -0,0 +1,29 @@
+# Damage
+
+Damage refers to the reduction of health points caused by the affected entity itself or a third party.
+Self-inflicted causes include, for instance, falling, drowning, or poison damage.
+Damage inflicted by a third party typically involves some form of hitting the affected entity.
+
+The `DamageSystem` handles damage dealt to entities with health.
+The `BlockDamageAuthoritySystem` enables blocks to sustain some damage before getting destroyed.
+The `DamageEffectAuthoritySystem` produces block particle effect in the event of damage.
+
+Send a `DoDamageEvent` to a specific entity to deal damage to it.
+
+Use the `DamageResistComponent` to configure an entity to not take damage from specific damage types.
+Examples for damage types are drowning (`engine:drowningDamage`) or explosive (`engine:explosiveDamage`) damage.
+The `DamageAuthoritySystem` considers the settings provided by this component before an entity is damaged.
+
+Damage sounds added to an entity via the `DamageSoundComponent` are randomly selected and played when the entity is damaged.
+Sounds should be referenced as `[engine|<module>]:<soundFileName>` for sound files located in the `assets/sounds` directory of the engine or a module, for instance `engine:Slime3`.
+
+Event chain:
+* `DoDamageEvent`
+* `BeforeDamageEvent`
+* Entity damaged, health component saved
-* Entity damaged, health component saved
+* _Entity damaged, health component saved_
-* Entity damaged, health component saved
+* _Entity damaged, health component saved_
+* `OnDamagedEvent`
+
+Commands:
+* `damageResist(damagetype,percentage)`: gives resistance to damage (damagetype = all for total resistance).
+* `damageImmune(damagetype)`: percentage = 100 by default.
+* `checkResistance()`: gives list of active resistance values
diff --git a/docs/health.md b/docs/health.md
@@ -0,0 +1,8 @@
+# Health
+
+Health determines the maximum amount of damage any entity to which the health concept applies can take before, for instance, being destroyed.
+
+The `HealthAuthoritySystem` handles changes to an entity's maximum health.
+The `HealthClientSystem` manages the current health of entities with health as well as the UI elements visually representing an entity's health status.
+
+Access the `HealthComponent` to retrieve information about an entity's maximum and current health, its damage thresholds, and whether or not the entity should be destroyed if its health drops to 0.
diff --git a/docs/regeneration.md b/docs/regeneration.md
@@ -1,9 +1,10 @@
 # Regeneration
 
-Handles the natural healing of entities (and blocks).
-To activate regeneration send `ActivateRegenEvent(String id, float value, float endTime)`. 
-Health is regenerated every second. 
-Empty event `ActivateRegenEvent()` activates base regeneration of entity.
+The `RegenAuthoritySystem` handles the natural healing of entities including players, NPCs, and even blocks.
 
-To deactivate particular type of regeneration, send `DeactivateRegenEvent(String id)`. 
-Empty event `DeactivateRegenEvent()` deactivates base regeneration fo entity.
+To activate regeneration send `ActivateRegenEvent(String id, float value, float endTime)` for a specific entity.
+This will result in health being regenerated for the specified entity every second. 
+Sending an empty event `ActivateRegenEvent()` activates the base regeneration for the specified entity.
+
+To deactivate a particular type of regeneration, send `DeactivateRegenEvent(String id)`. 
+Sending an empty event `DeactivateRegenEvent()` deactivates the base regeneration for the specified entity.
diff --git a/docs/restoration.md b/docs/restoration.md
@@ -1,6 +1,7 @@
 # Restoration
 
-Handles magical healing of entities. 
+The `RestorationAuthoritySystem` handles the magical healing of entities.
+
 To heal an entity, send `DoRestoreEvent(amount, instigatorRef)`. 
 
 The event chain of restoration:

diff --git a/docs/system-block-damage.md b/docs/system-block-damage.md
diff --git a/docs/system-damage.md b/docs/system-damage.md
diff --git a/docs/ui-damage-overlay.md b/docs/ui-damage-overlay.md
@@ -0,0 +1,14 @@
+# Damage Overlay
+
+The `Health` module adds a visual overlay whenever the you are damaged.
+If you hurt yourself, for instance through drowning or fall damage, the default damage overlay is displayed.
+It consists of four red indicators, one on each side of your screen.
+The default damage overlay is also shown when you are hurt by an effect such as poison.
+
+![Damage Overlay](./_media/damage-overlay.jpg)
+
+In case of an external cause, for instance another player or an NPC attacking you, the overlay will be directional.
+There will only be one red indicator, marking the direction of origin of the damage cause.
+This will allow you to locate the external cause that is hurting you.
+
+![Damage Overlay](./_media/directional-damage-overlay.jpg)
diff --git a/docs/ui-hud.md b/docs/ui-hud.md
@@ -0,0 +1,9 @@
+# Health HUD
+
+The `Health` module extends the Player HUD with a health bar consisting of red hearts.
+
+![Health HUD](./_media/hud.jpg)
+
+When you receive damage, you will lose health, visualized by the full hearts being drained from the right to the left.
+Once all the hearts in your health bar are empty, you will die.
+You start automatically regenerating health over time once you are no longer being damaged.