Add javadoc to restore events and RestorationAuthoritySystem

src/main/java/org/terasology/logic/health/RestorationAuthoritySystem.java

@@ -28,6 +28,17 @@
 import org.terasology.logic.players.event.OnPlayerRespawnedEvent;
 import org.terasology.math.TeraMath;
 
+/**
+ * This system takes care of restoration of entities with HealthComponent.
+ * To increase the health of an entity, send DoRestoreEvent
+ * <p>
+ * Logic flow for restoration:
+ * - DoRestoreEvent
+ * - BeforeRestoreEvent
+ * - (HealthComponent saved)
+ * - OnRestoredEvent
+ * - OnFullyHealedEvent (if healed to full health)
+ */
 @RegisterSystem(RegisterMode.AUTHORITY)
 public class RestorationAuthoritySystem extends BaseComponentSystem {
 
@@ -39,7 +50,8 @@ public void onRestore(DoRestoreEvent event, EntityRef entity, HealthComponent he
             if (modifiedRestoreAmount > 0) {
                 restore(entity, health, modifiedRestoreAmount);
             } else {
-                entity.send(new DoDamageEvent(-modifiedRestoreAmount));
+                // Cause "healing" damage to entity if modified value of restoration is negative
+                entity.send(new DoDamageEvent(-modifiedRestoreAmount, EngineDamageTypes.HEALING.get()));
             }
         }
     }

src/main/java/org/terasology/logic/health/event/BeforeRestoreEvent.java

@@ -24,7 +24,7 @@
  * Modifications are accumulated as modifiers (additions), multipliers and postModifiers (additions after multipliers).
  */
 public class BeforeRestoreEvent extends AbstractConsumableValueModifiableEvent {
-    /** The entity which is being regenerated. */
+    /** The entity which is being restored. */
     private EntityRef entity;
 
     /**

src/main/java/org/terasology/logic/health/event/DoRestoreEvent.java

@@ -15,6 +15,7 @@
  */
 package org.terasology.logic.health.event;
 
+import org.terasology.entitySystem.entity.EntityRef;
 import org.terasology.entitySystem.event.Event;
 
 /**
@@ -23,13 +24,20 @@
 public class DoRestoreEvent implements Event {
     /** The amount of health points being restored. */
     private int amount;
+    /** The instigator of restoration */
+    private EntityRef instigator;
 
     /**
      * Constructor for event providing amount of restoration.
      * @param amount    The amount of restoration.
      */
     public DoRestoreEvent(int amount) {
+        this(amount, EntityRef.NULL);
+    }
+
+    public DoRestoreEvent(int amount, EntityRef entity) {
         this.amount = amount;
+        this.instigator = entity;
     }
 
     /**
@@ -39,4 +47,12 @@ public DoRestoreEvent(int amount) {
     public int getAmount() {
         return amount;
     }
+
+    /**
+     * Method to get the instigator of restoration.
+     * @return EntityRef of instigator.
+     */
+    public EntityRef getInstigator() {
+        return instigator;
+    }
 }

src/main/java/org/terasology/logic/health/event/OnRestoredEvent.java

@@ -17,14 +17,29 @@
 
 import org.terasology.entitySystem.entity.EntityRef;
 
+/**
+ * This event is sent after the entity is restored. Final event of restoration logic.
+ */
 public class OnRestoredEvent extends HealthChangedEvent {
+    /**
+     * The amount by which the entity is restored.
+     */
     private int amount;
 
+    /**
+     * Constructor for creating the event.
+     * @param amount        The amount of restoration.
+     * @param instigator    EntityRef of cause of restoration.
+     */
     public OnRestoredEvent(int amount, EntityRef instigator) {
         super(instigator, amount);
         this.amount = amount;
     }
 
+    /**
+     * Method to get the amount of restoration.
+     * @return amount of restoration.
+     */
     public int getRegenAmount() {
         return amount;
     }