Merge branch 'api-8' into api-9

Author: dualspiral

src/main/java/org/spongepowered/api/Server.java

@@ -42,6 +42,7 @@
 import org.spongepowered.api.scoreboard.Scoreboard;
 import org.spongepowered.api.service.ServiceProvider;
 import org.spongepowered.api.user.UserManager;
+import org.spongepowered.api.util.Ticks;
 import org.spongepowered.api.util.locale.LocaleSource;
 import org.spongepowered.api.world.difficulty.Difficulty;
 import org.spongepowered.api.world.generation.config.WorldGenerationConfig;
@@ -278,7 +279,7 @@ public interface Server extends ForwardingAudience, Engine, LocaleSource {
      *
      * @return The number of ticks since this server started running
      */
-    int runningTimeTicks();
+    Ticks runningTimeTicks();
 
     /**
      * Gets the message channel that server-wide messages are sent through.

src/main/java/org/spongepowered/api/config/DefaultConfig.java

@@ -27,21 +27,23 @@
 import com.google.inject.BindingAnnotation;
 import com.google.inject.Inject;
 import org.spongepowered.configurate.loader.ConfigurationLoader;
+import org.spongepowered.configurate.reference.ConfigurationReference;
 
-import java.io.File;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import java.nio.file.Path;
 
 /**
- * Provides an convenient injection for {@link ConfigRoot#config()} or
+ * Provides a convenient injection for {@link ConfigRoot#config()} or
  * {@link ConfigRoot#configPath()}.
  *
- * <p>Use this annotation on a {@link File} or {@link Path} if you want the
+ * <p>Use this annotation on a {@link Path} if you want the
  * pathname to the default configuration. Or instead, use this annotation on a
- * {@link ConfigurationLoader} to get an instance of that. Remember that
+ * {@link ConfigurationLoader ConfigurationLoader&lt;CommentedConigurationNode&gt;}
+ * or {@link ConfigurationReference ConfigurationReference&lt;CommentedConigurationNode&gt;}
+ * to get a loader/reference for a HOCON based configuration file. Remember that
  * {@link Inject} is also necessary.</p>
  *
  * @see ConfigManager For getting configuration without injection

src/main/java/org/spongepowered/api/data/Key.java

@@ -81,11 +81,6 @@ public interface Key<V extends Value<?>> extends ResourceKeyed {
      * Sponge. If custom keys for {@link DataHolder}s is desired to be
      * persisted, a {@link DataRegistration} is required.
      *
-     * <p>Registration of a custom created {@link Key} is required through
-     * {@link RegisterRegistryValueEvent}. The
-     * registration of a {@link DataRegistration} is done separately.
-     * </p>
-     *
      * @see DataRegistration
      * @return The key builder
      */

src/main/java/org/spongepowered/api/entity/ai/goal/builtin/creature/RangedAttackAgainstAgentGoal.java

@@ -29,6 +29,7 @@
 import org.spongepowered.api.entity.ai.goal.Goal;
 import org.spongepowered.api.entity.ai.goal.GoalBuilder;
 import org.spongepowered.api.entity.living.Ranger;
+import org.spongepowered.api.util.Ticks;
 
 /**
  * An {@link Goal} which uses the ranging aspect of the Ranger to attack
@@ -68,7 +69,7 @@ static Builder builder() {
      *
      * @return The delay in ticks between attempts to attack
      */
-    int delayBetweenAttacks();
+    Ticks delayBetweenAttacks();
 
     /**
      * The time, in ticks, this {@link Ranger} will wait before attacking
@@ -77,7 +78,7 @@ static Builder builder() {
      * @param delay The delay, in ticks
      * @return This goal, for chaining
      */
-    RangedAttackAgainstAgentGoal setDelayBetweenAttacks(int delay);
+    RangedAttackAgainstAgentGoal setDelayBetweenAttacks(Ticks delay);
 
     /**
      * Gets the radius of which the owning {@link Ranger} will attempt to
@@ -101,7 +102,7 @@ interface Builder extends GoalBuilder<Ranger, RangedAttackAgainstAgentGoal, Buil
 
         Builder moveSpeed(double speed);
 
-        Builder delayBetweenAttacks(int delay);
+        Builder delayBetweenAttacks(Ticks delay);
 
         Builder attackRadius(float radius);
     }

src/main/java/org/spongepowered/api/entity/living/player/CooldownTracker.java

@@ -25,9 +25,10 @@
 package org.spongepowered.api.entity.living.player;
 
 import org.spongepowered.api.item.ItemType;
+import org.spongepowered.api.util.Ticks;
 
+import java.util.Optional;
 import java.util.OptionalDouble;
-import java.util.OptionalInt;
 
 /**
  * Provides access to the item cooldowns of a {@link Player}.
@@ -51,7 +52,7 @@ public interface CooldownTracker {
      * @return The cooldown remaining for this item type in ticks, if not
      *     on cooldown
      */
-    OptionalInt cooldown(ItemType type);
+    Optional<Ticks> cooldown(ItemType type);
 
     /**
      * Sets the cooldown for the specified {@link ItemType} for the
@@ -62,7 +63,7 @@ public interface CooldownTracker {
      * @return False if setting the cooldown failed, possibly due to the event
      *     being cancelled
      */
-    boolean setCooldown(ItemType type, int ticks);
+    boolean setCooldown(ItemType type, Ticks ticks);
 
     /**
      * Resets the cooldown of the specified {@link ItemType} for the

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

@@ -27,6 +27,7 @@
 import org.spongepowered.api.entity.Entity;
 import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.Event;
+import org.spongepowered.api.util.Ticks;
 
 /**
  * An event that occurs when an entity becomes ignited.
@@ -44,20 +45,20 @@ public interface IgniteEntityEvent extends Event, Cancellable {
      * Gets the original amount of fire ticks the entity will remain on fire.
      * @return The original fire ticks
      */
-    int originalFireTicks();
+    Ticks originalFireTicks();
 
     /**
      * Gets the amount of ticks the entity will remain on fire.
      *
      * @return The amount of ticks the entity will remain on fire
      */
-    int fireTicks();
+    Ticks fireTicks();
 
     /**
      * Sets the amount of ticks the entity will remain on fire.
      *
      * @param fireTicks The amount of ticks the entity will remain on fire
      */
-    void setFireTicks(int fireTicks);
+    void setFireTicks(Ticks fireTicks);
 
 }

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

@@ -38,10 +38,6 @@
  *
  * <p>Note: To determine the {@link Cause}, refer to package
  * org.spongepowered.api.event.cause.entity.spawn.</p>
- *
- * <p>For players, this event is fired before they have fully
- * joined the world. {@link ServerSideConnectionEvent} is the
- * recommended event to interact with connecting players.</p>
  */
 @GenerateFactoryMethod
 @ImplementedBy(value = AbstractSpawnEntityEvent.class, priority = 2)

src/main/java/org/spongepowered/api/event/entity/living/player/CooldownEvent.java

@@ -29,7 +29,9 @@
 import org.spongepowered.api.event.Cancellable;
 import org.spongepowered.api.event.Event;
 import org.spongepowered.api.item.ItemType;
+import org.spongepowered.api.util.Ticks;
 
+import java.util.Optional;
 import java.util.OptionalInt;
 
 /**
@@ -64,28 +66,28 @@ interface Set extends CooldownEvent, Cancellable {
          *
          * @return The cooldown of the item type beforehand
          */
-        OptionalInt startingCooldown();
+        Optional<Ticks> startingCooldown();
 
         /**
          * Gets the original new set cooldown at the beginning of the event.
          *
          * @return The originally set cooldown
          */
-        int originalNewCooldown();
+        Ticks originalNewCooldown();
 
         /**
          * Gets the new cooldown the item type has for the player.
          *
          * @return The new cooldown of the item type
          */
-        int newCooldown();
+        Ticks newCooldown();
 
         /**
          * Sets the new cooldown for the item type for the player.
          *
          * @param ticks The amount of ticks the cooldown should last for
          */
-        void setNewCooldown(int ticks);
+        void setNewCooldown(Ticks ticks);
 
     }
 

src/main/java/org/spongepowered/api/event/item/inventory/UseItemStackEvent.java

@@ -30,6 +30,7 @@
 import org.spongepowered.api.item.ItemType;
 import org.spongepowered.api.item.inventory.ItemStack;
 import org.spongepowered.api.item.inventory.ItemStackSnapshot;
+import org.spongepowered.api.util.Ticks;
 
 /**
  * Fired when an {@link ItemStack} is used.
@@ -41,21 +42,21 @@ public interface UseItemStackEvent extends Event {
      *
      * @return The original remaining duration
      */
-    int originalRemainingDuration();
+    Ticks originalRemainingDuration();
 
     /**
      * Gets the remaining duration of {@link ItemStack} in use.
      *
      * @return The remaining duration
      */
-    int remainingDuration();
+    Ticks remainingDuration();
 
     /**
      * Sets the remaining duration of {@link ItemStack} in use.
      *
      * @param duration The remaining duration to set
      */
-    void setRemainingDuration(int duration);
+    void setRemainingDuration(Ticks duration);
 
     /**
      * Gets the {@link ItemStack} being consumed.

src/main/java/org/spongepowered/api/event/network/ServerSideConnectionEvent.java

@@ -47,18 +47,17 @@
 /**
  * Represents an event fired during the login process.
  *
- * <p>Together with {@link SpawnEntityEvent}, these events represent the
- * progression of a {@link ServerPlayer player} from first authenticating, to being fully
- * loaded in the world.</p>
+ * <p>These events represent the progression of a {@link ServerPlayer player}
+ * from first authenticating, to being fully loaded in the world.</p>
  *
  * <p>The events are fired in the following order:</p>
  *
- * <p>#Auth -&gt; #Handshake -&gt; #Login -&gt; {@link SpawnEntityEvent} -&gt; #Join</p>
+ * <p>#Auth -&gt; #Handshake -&gt; #Login -&gt; #Join</p>
  *
- * <p>{@link SpawnEntityEvent} is still fired for players, for consistency.
- * However, the player is not at a well-defined state at that point. It's
- * recommended to use the event's subinterfaces to interact with the player
- * at well-defined moments during the connection process.</p>
+ * <p>Traditionally one could consider a {@link SpawnEntityEvent} to be thrown,
+ * but due to the nature of cancellations, a {@link ServerPlayer player} joining
+ * a world after {@link Login login} would be inadvisable to cancel due to the
+ * inconsistent state of both the player and the player's client.</p>
  */
 public interface ServerSideConnectionEvent extends Event {
 
@@ -182,11 +181,13 @@ interface Login extends ServerSideConnectionEvent, MessageEvent, Event, Cancella
     }
 
     /**
-     * Called when a {@link ServerPlayer player} joins the game within a {@link ServerWorld world} for the first
-     * time after initial connection.
-     *
-     * <p>The {@link SpawnEntityEvent} for the {@link ServerPlayer player} is fired after the
-     * #Login event. This event is fired after both.</p>
+     * Called when a {@link ServerPlayer player} joins the game within a
+     * {@link ServerWorld world} for the first time after initial connection.
+     * Fired after {@link Login} once the {@link ServerPlayer player} has been
+     * properly added to the {@link ServerWorld}. If data is wanted to be
+     * modified that could affect a player's representation (such as vanishing),
+     * it's recommended to modify such data in the logging in
+     * {@link Login#user() User} instead.
      */
     interface Join extends ServerSideConnectionEvent, AudienceMessageEvent, MessageCancellable {