diff --git a/docs/_media/damage-overlay.jpg b/docs/_media/damage-overlay.jpg new file mode 100644 index 0000000..1fe003f Binary files /dev/null and b/docs/_media/damage-overlay.jpg differ diff --git a/docs/_media/directional-damage-overlay.jpg b/docs/_media/directional-damage-overlay.jpg new file mode 100644 index 0000000..31a03e9 Binary files /dev/null and b/docs/_media/directional-damage-overlay.jpg differ diff --git a/docs/_media/hud.jpg b/docs/_media/hud.jpg new file mode 100644 index 0000000..3be5380 Binary files /dev/null and b/docs/_media/hud.jpg differ diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 7be35d8..91ab76e 100644 --- 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) \ No newline at end of file diff --git a/docs/damage.md b/docs/damage.md new file mode 100644 index 0000000..14dc630 --- /dev/null +++ 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|]:` 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_ +* `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 new file mode 100644 index 0000000..9d12bb0 --- /dev/null +++ b/docs/health.md @@ -0,0 +1,9 @@ +# Health + +Health determines the maximum amount of damage any entity can take, for instance, before being destroyed. +The health of an entity is measured in discrete steps, often called hit points (HP). + +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 index 058c74f..e10f91d 100644 --- 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/restoration.md b/docs/restoration.md index aaabb37..c9ed6ac 100644 --- 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 deleted file mode 100644 index bd760c6..0000000 --- a/docs/system-block-damage.md +++ /dev/null @@ -1,3 +0,0 @@ -# Block Damage System - -Enables block to sustain some damage before getting destroyed, and produces block particle effect on damage. \ No newline at end of file diff --git a/docs/system-damage.md b/docs/system-damage.md deleted file mode 100644 index 8ea2c8d..0000000 --- a/docs/system-damage.md +++ /dev/null @@ -1,15 +0,0 @@ -# Damage System - -Handles damage dealt to entities with health. Send `DoDamageEvent` -to deal damage to entity. - -Event chain: -* DoDamageEvent -* BeforeDamageEvent -* 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 \ No newline at end of file diff --git a/docs/ui-damage-overlay.md b/docs/ui-damage-overlay.md new file mode 100644 index 0000000..139fd49 --- /dev/null +++ b/docs/ui-damage-overlay.md @@ -0,0 +1,13 @@ +# Damage Overlay + +The `Health` module adds a visual overlay whenever the you are damaged. +If you hurt yourself (self-inflicted damage), for instance through falling, drowning, or poisoning, the default damage overlay is displayed. +It consists of four red indicators, one on each side of your screen. + +![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 new file mode 100644 index 0000000..97f502c --- /dev/null +++ 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.