Add a Cause to DamageModifier and remove DamageStep subclasses

Author: Yeregorix

src/main/java/org/spongepowered/api/event/cause/entity/damage/DamageModifier.java

@@ -25,25 +25,37 @@
 package org.spongepowered.api.event.cause.entity.damage;
 
 import org.spongepowered.api.Sponge;
+import org.spongepowered.api.event.Cause;
+
+import java.util.Optional;
 
 /**
- * A damage modifier that will be applied before or after a {@link DamageStep}.
+ * A damage modifier that is or may become a {@link DamageStep}.
  */
 public interface DamageModifier {
 
     /**
      * Gets the {@link DamageStepType} of this modifier.
      *
-     * @return the modifier type.
+     * @return the step type
      */
     DamageStepType type();
 
+    /**
+     * Gets the {@link Cause} of this modifier.
+     *
+     * @return The cause
+     */
+    Cause cause();
+
     /**
      * Gets the function that modify the damage.
+     * The function may be absent if the sole purpose of this modifier is to apply children steps,
+     * or if the step was made by the platform, usually the root step.
      *
-     * @return the modifier function.
+     * @return the modifier function
      */
-    Function function();
+    Optional<Function> function();
 
     @FunctionalInterface
     interface Function {
@@ -57,11 +69,42 @@ interface Function {
         double modify(DamageStep step, double damage);
     }
 
-    static DamageModifier of(DamageStepType type, Function function) {
-        return Sponge.game().factoryProvider().provide(Factory.class).of(type, function);
+    /**
+     * Creates a new {@link Builder} to create {@link DamageModifier}s.
+     *
+     * @return The new builder
+     */
+    static Builder builder() {
+        return Sponge.game().builderProvider().provide(Builder.class);
     }
 
-    interface Factory {
-        DamageModifier of(DamageStepType type, Function function);
+    /**
+     * A builder to create {@link DamageModifier}s.
+     */
+    interface Builder extends org.spongepowered.api.util.Builder<DamageModifier, Builder> {
+
+        /**
+         * Sets the {@link DamageStepType} for this modifier.
+         *
+         * @param type The damage step type
+         * @return this builder for chaining
+         */
+        Builder type(DamageStepType type);
+
+        /**
+         * Sets the {@link Cause} for this modifier.
+         *
+         * @param cause The modifier cause
+         * @return this builder for chaining
+         */
+        Builder cause(Cause cause);
+
+        /**
+         * Sets the {@link Function} for this modifier.
+         *
+         * @param function The modifier function
+         * @return this builder for chaining
+         */
+        Builder function(Function function);
     }
 }

src/main/java/org/spongepowered/api/event/cause/entity/damage/DamageStep.java

@@ -24,23 +24,16 @@
  */
 package org.spongepowered.api.event.cause.entity.damage;
 
-import org.spongepowered.api.event.Cause;
-
 import java.util.List;
+import java.util.Optional;
 import java.util.OptionalDouble;
 
 /**
- * Represents a tree of steps in the damage calculation.
+ * A step represent an operation made by the platform (vanilla and mods) or modifiers added by plugins.
+ * Steps are structured as trees where children modify the input or output of the parent step.
  * A damage calculation is made of multiple trees of steps.
  */
-public interface DamageStep {
-
-    /**
-     * Gets the {@link DamageStepType} for this step.
-     *
-     * @return The damage step type
-     */
-    DamageStepType type();
+public interface DamageStep extends DamageModifier {
 
     /**
      * Gets whether this step is skipped.
@@ -103,42 +96,38 @@ default void skip() {
     OptionalDouble damageAfterChildren();
 
     /**
-     * Gets an immutable list of all children steps that applies just before this step.
+     * Gets the parent of this step.
+     * Returns empty if this step is the root of its tree.
      *
-     * @return The list of children steps
+     * @return The parent of this step
      */
-    List<DamageStep.Child> childrenBefore();
+    Optional<DamageStep> parent();
 
     /**
-     * Gets an immutable list of all children steps that applies just after this step.
+     * Gets the root of this step.
      *
-     * @return The list of children steps
+     * @return The root of this step
      */
-    List<DamageStep.Child> childrenAfter();
+    default DamageStep root() {
+        DamageStep step = this;
+        Optional<DamageStep> parent;
+        while ((parent = step.parent()).isPresent()) {
+            step = parent.get();
+        }
+        return step;
+    }
 
     /**
-     * Represents a step made by the platform (vanilla and mods).
+     * Gets an immutable list of all children steps that applies just before this step.
+     *
+     * @return The list of children steps
      */
-    interface Root extends DamageStep {
-
-        /**
-         * Gets the {@link Cause} of this step.
-         *
-         * @return The cause of this step
-         */
-        Cause cause();
-    }
+    List<DamageStep> childrenBefore();
 
     /**
-     * Represents a step made by a plugin (a modifier).
+     * Gets an immutable list of all children steps that applies just after this step.
+     *
+     * @return The list of children steps
      */
-    interface Child extends DamageStep, DamageModifier {
-
-        /**
-         * Gets the parent of this step.
-         *
-         * @return The parent of this step
-         */
-        DamageStep parent();
-    }
+    List<DamageStep> childrenAfter();
 }

src/main/java/org/spongepowered/api/event/cause/entity/damage/DamageStepTypes.java

@@ -69,7 +69,7 @@ public final class DamageStepTypes {
      * the {@link EnchantmentType}s applicable to an {@link ItemStack} that is
      * considered to be "armor" currently equipped on the owner.
      *
-     * <p>Usually, within the {@link DamageStep.Root#cause()} will reside
+     * <p>Usually, within the {@link DamageStep#cause()} will reside
      * an {@link ItemStackSnapshot} and an {@link Enchantment} signifying
      * that the {@link EnchantmentType} of the {@link ItemStack} is modifying the
      * incoming/outgoing damage. There can be multiple {@link DamageStep}s
@@ -96,7 +96,7 @@ public final class DamageStepTypes {
      * the {@link PotionEffectTypes#RESISTANCE} or any other
      * {@link PotionEffectType} that can be deemed as reducing incoming damage.
      *
-     * <p>Usually, within the {@link DamageStep.Root#cause()} will reside
+     * <p>Usually, within the {@link DamageStep#cause()} will reside
      * a {@link PotionEffect} including the amplifier and duration, signifying
      * that the {@link PotionEffectType} is modifying the incoming damage.</p>
      */
@@ -125,7 +125,7 @@ public final class DamageStepTypes {
      * Represents the {@link DamageStep} that will modify damage from
      * a {@link DamageSource#source()} that is a {@link org.spongepowered.api.entity.FallingBlock}.
      *
-     * <p>Usually, within the {@link DamageStep.Root#cause()} will reside
+     * <p>Usually, within the {@link DamageStep#cause()} will reside
      * an {@link ItemStackSnapshot} and an {@link Enchantment} signifying
      * that the {@link EnchantmentType} of the {@link ItemStack} is modifying the
      * incoming/outgoing damage.</p>
@@ -142,7 +142,7 @@ public final class DamageStepTypes {
      * Represents a {@link DamageStep} that will reduce outgoing damage
      * based on a {@link PotionEffect}.
      *
-     * <p>Usually, within the {@link DamageStep.Root#cause()} will reside
+     * <p>Usually, within the {@link DamageStep#cause()} will reside
      * a {@link PotionEffect} including the amplifier and duration, signifying
      * that the {@link PotionEffectType} is reducing the outgoing damage.</p>
      */
@@ -180,7 +180,7 @@ public final class DamageStepTypes {
      * Represents the {@link DamageStep} that will modify damage from
      * an {@link EnchantmentType} on an equipped {@link ItemStack}.
      *
-     * <p>Usually, within the {@link DamageStep.Root#cause()} will reside
+     * <p>Usually, within the {@link DamageStep#cause()} will reside
      * an {@link ItemStackSnapshot} and an {@link Enchantment} signifying
      * that the {@link EnchantmentType} of the {@link ItemStack} is modifying the
      * incoming/outgoing damage.</p>

src/main/java/org/spongepowered/api/event/entity/DamageCalculationEvent.java

@@ -123,6 +123,6 @@ interface Post extends DamageCalculationEvent {
          *
          * @return The list of root steps
          */
-        List<DamageStep.Root> steps();
+        List<DamageStep> steps();
     }
 }