Merge Vanish API updates into API 9

Author: gabizou

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

@@ -95,6 +95,7 @@
 import org.spongepowered.api.data.value.SetValue;
 import org.spongepowered.api.data.value.Value;
 import org.spongepowered.api.data.value.WeightedCollectionValue;
+import org.spongepowered.api.effect.VanishState;
 import org.spongepowered.api.effect.particle.ParticleEffect;
 import org.spongepowered.api.effect.particle.ParticleOption;
 import org.spongepowered.api.effect.particle.ParticleType;
@@ -1413,7 +1414,7 @@ public final class Keys {
      * Whether an {@link Entity} is currently invisible.
      * This will only simply render the entity as vanished,
      * but not prevent any entity updates being sent to clients.
-     * To fully "vanish" an {@link Entity}, use {@link #VANISH}.
+     * To fully "vanish" an {@link Entity}, use {@link #VANISH_STATE}.
      */
     public static final Key<Value<Boolean>> IS_INVISIBLE = Keys.key(ResourceKey.sponge("is_invisible"), Boolean.class);
 
@@ -2672,6 +2673,19 @@ public final class Keys {
      */
     public static final Key<Value<Boolean>> UPDATE_GAME_PROFILE = Keys.key(ResourceKey.sponge("update_game_profile"), Boolean.class);
 
+    /**
+     * The {@link VanishState} of an {@link Entity}.
+     *
+     * <p>The presence of a vanished entity will not be made known to a client;
+     * no packets pertaining to this entity are sent. Client-side, this entity
+     * will cease to exist. Server-side it may still be targeted by hostile
+     * entities or collide with other entities.</p>
+     *
+     * <p>Vanishing an {@link Entity} ridden by other entities (see
+     * {@link #PASSENGERS} will cause problems.</p>
+     */
+    public static final Key<Value<VanishState>> VANISH_STATE = Keys.key(ResourceKey.sponge("vanish"), VanishState.class);
+
     /**
      * Whether an {@link Entity} is vanished.
      *
@@ -2682,15 +2696,19 @@ public final class Keys {
      *
      * <p>Vanishing an {@link Entity} ridden by other entities (see
      * {@link #PASSENGERS} will cause problems.</p>
+     * @deprecated use {@link #VANISH_STATE}
      */
+    @Deprecated
     public static final Key<Value<Boolean>> VANISH = Keys.key(ResourceKey.sponge("vanish"), Boolean.class);
 
     /**
      * Whether an {@link Entity} ignores collision with other entities.
      *
      * <p>This state will be ignored if the {@link Entity} is not also
      * vanished as per {@link #VANISH}.</p>
+     * @deprecated use {@link #VANISH_STATE}
      */
+    @Deprecated
     public static final Key<Value<Boolean>> VANISH_IGNORES_COLLISION = Keys.key(ResourceKey.sponge("vanish_ignores_collision"), Boolean.class);
 
     /**
@@ -2700,7 +2718,9 @@ public final class Keys {
      *
      * <p>This state will be ignored if the {@link Entity} is not also
      * vanished as per {@link #VANISH}.}.</p>
+     * @deprecated use {@link #VANISH_STATE}
      */
+    @Deprecated
     public static final Key<Value<Boolean>> VANISH_PREVENTS_TARGETING = Keys.key(ResourceKey.sponge("vanish_prevents_targeting"), Boolean.class);
 
     /**

src/main/java/org/spongepowered/api/effect/VanishState.java

@@ -0,0 +1,252 @@
+/*
+ * This file is part of SpongeAPI, licensed under the MIT License (MIT).
+ *
+ * Copyright (c) SpongePowered <https://www.spongepowered.org>
+ * Copyright (c) contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+package org.spongepowered.api.effect;
+
+import org.spongepowered.api.Sponge;
+import org.spongepowered.api.entity.Entity;
+
+/**
+ * Represents the state of an {@link Entity}'s vanish state.
+ * Accessible through {@link org.spongepowered.api.data.Keys#VANISH_STATE}
+ */
+public interface VanishState {
+
+    /**
+     * Gets a vanished state via {@link Factory#vanish()} with the following
+     * defaults:
+     * <ul>
+     *     <li>{@link VanishState#invisible()} = {@code true}</li>
+     *     <li>{@link VanishState#affectsMonsterSpawning()} = {@code false}</li>
+     *     <li>{@link VanishState#untargetable()} = {@code true}</li>
+     *     <li>{@link VanishState#createsSounds()} = {@code false}</li>
+     *     <li>{@link VanishState#createsParticles()} = {@code false}</li>
+     *     <li>{@link VanishState#triggerVibrations()} = {@code false}</li>
+     * </ul>
+     *
+     * @return A vanished state with the provided defaults
+     */
+    static VanishState vanished() {
+        return Sponge.game().factoryProvider().provide(VanishState.Factory.class).vanished();
+    }
+
+    /**
+     * A {@link VanishState} that is invisible with the following defaults:
+     * <ul>
+     *     <li>{@link VanishState#invisible()} = {@code false}</li>
+     *     <li>{@link VanishState#affectsMonsterSpawning()} = {@code true}</li>
+     *     <li>{@link VanishState#untargetable()} = {@code false}</li>
+     *     <li>{@link VanishState#createsSounds()} = {@code true}</li>
+     *     <li>{@link VanishState#createsParticles()} = {@code true}</li>
+     *     <li>{@link VanishState#triggerVibrations()} = {@code false}</li>
+     * </ul>
+     *
+     * @return A visible state with the provided defaults
+     */
+    static VanishState unvanished() {
+        return Sponge.game().factoryProvider().provide(VanishState.Factory.class).unvanished();
+    }
+
+    /**
+     * Gets whether the state is visible. If an {@link Entity} is visible, then
+     * other aspects of this state will be ignored, such as
+     * {@link #ignoresCollisions()}, {@link #untargetable()}, etc.
+     *
+     * @return Whether the {@link Entity} is visible
+     */
+    boolean invisible();
+
+    /**
+     * Gets a vanished {@link VanishState state} with {@link #ignoresCollisions()}
+     * and {@link #untargetable()} set to {@code true}. If the state is already
+     * {@link #invisible()}, then the same state is returned.
+     *
+     * @return The vanished state
+     */
+    VanishState vanish();
+
+    /**
+     * Gets a visible state {@link VanishState} with {@link #ignoresCollisions()}
+     * and {@link #untargetable()} set to {@code false}. If the state is already
+     * {@link #invisible()} being {@code false}, then the same state is returned.
+     *
+     * @return The visible state
+     */
+    VanishState unvanish();
+
+    /**
+     * Gets if the {@link Entity} will ignore collisions. In cases where
+     * {@link #invisible()} is {@code false}, this will return {@code false}.
+     *
+     * @return Whether collisions will be ignored
+     */
+    boolean ignoresCollisions();
+
+    /**
+     * If {@link #invisible()} returns true, this will return the
+     * {@link VanishState} with the desired flag of
+     * {@link #ignoresCollisions()}.
+     *
+     * @param ignoresCollisions Whether collisions will be ignored
+     * @return The new VanishState, the value changed
+     */
+    VanishState ignoreCollisions(boolean ignoresCollisions);
+
+    /**
+     * Gets if the {@link Entity} will be untargetable by entity ai. In cases
+     * where {@link #invisible()} is {@code false}, this will return
+     * {@code false}.
+     *
+     * @return Whether the {@link Entity} will be untargetable
+     */
+    boolean untargetable();
+
+    /**
+     * If {@link #invisible()} returns true, this will return the
+     * {@link VanishState} with the desired flag of
+     * {@link #ignoresCollisions()}.
+     *
+     * @param untargetable Whether the entity can be targeted by AI
+     * @return The new VanishState, the value changed
+     */
+    VanishState untargetable(boolean untargetable);
+
+    /**
+     * Gets if {@link #affectsMonsterSpawning()} returns {@code false}, the
+     * vanished {@link Entity} will not spawn monsters or affect near by monster
+     * spawners.
+     * <p>Note that this flag works in conjunction with
+     * {@link org.spongepowered.api.data.Keys#AFFECTS_SPAWNING} such that either
+     * one being {@code false} will disable spawning.</p>
+     *
+     * @return Whether the {@link Entity} will affect monster spawning
+     */
+    boolean affectsMonsterSpawning();
+
+    /**
+     * If {@link #invisible()} returns true, this will return the
+     * {@link VanishState} with the desired flag.
+     * <p>Note that this flag works in conjunction with
+     * {@link org.spongepowered.api.data.Keys#AFFECTS_SPAWNING} such that either
+     * one being false will disable spawning.</p>
+     *
+     * @param affectsMonsterSpawning Whether the {@link Entity} will affect
+     *      monster spawning
+     * @return The new VanishState
+     */
+    VanishState affectMonsterSpawning(boolean affectsMonsterSpawning);
+
+    /**
+     * Gets if the {@link Entity} will produce sounds from various actions that
+     * occur while {@link #invisible()} is {@code true}.
+     *
+     * @return Whether the {@link Entity} will produce sounds while invisible
+     */
+    boolean createsSounds();
+
+    /**
+     * If {@link #invisible()} returns true, this will return the
+     * {@link VanishState} with the desired flag of
+     * {@link #createsSounds()}.
+     *
+     * @param createSounds Whether the {@link Entity} will produce sounds
+     * @return The new VanishState
+     */
+    VanishState createSounds(boolean createSounds);
+
+    /**
+     * Gets if the {@link Entity} will produce particles from various actions
+     * that occur while {@link #invisible()} is {@code true}.
+     *
+     * @return Whether the {@link Entity} will produce particles while invisible
+     */
+    boolean createsParticles();
+
+    /**
+     * If {@link #invisible()} returns true, this will return the
+     * {@link VanishState} with the desired flag of
+     * {@link #createsParticles()}.
+     *
+     * @param createParticles Whether the {@link Entity} will produce particles
+     * @return The new VanishState
+     */
+    VanishState createParticles(boolean createParticles);
+
+    /**
+     * Gets if the {@link Entity} will trigger vibrations
+     * from various actions while vanished. These vibrations
+     * are generally measured/reacted by
+     * {@link org.spongepowered.api.block.entity.SculkSensor SculkSensors}
+     * and potentially create particles.
+     *
+     * @return Whether the {@link Entity} will trigger vibrations
+     *     while invisible
+     */
+    boolean triggerVibrations();
+
+    /**
+     * If {@link #invisible()} returns true, this will return the
+     * {@link VanishState} with the desired flag replacing
+     * {@link #triggerVibrations()}.
+     *
+     * @param triggerVibrations Whether the {@link Entity} will trigger
+     *     vibrations while invisible
+     * @return The new VanishState
+     */
+    VanishState triggerVibrations(boolean triggerVibrations);
+
+    interface Factory {
+
+        /**
+         * Creates a {@link VanishState} that is invisible with the following
+         * defaults:
+         * <ul>
+         *     <li>{@link VanishState#invisible()} = {@code true}</li>
+         *     <li>{@link VanishState#affectsMonsterSpawning()} = {@code false}</li>
+         *     <li>{@link VanishState#untargetable()} = {@code true}</li>
+         *     <li>{@link VanishState#createsSounds()} = {@code false}</li>
+         *     <li>{@link VanishState#createsParticles()} = {@code false}</li>
+         *     <li>{@link VanishState#triggerVibrations()} = {@code false}</li>
+         * </ul>
+         *
+         * @return A newly created invisible {@link VanishState}
+         */
+        VanishState vanished();
+
+        /**
+         * A {@link VanishState} that is visible with the following defaults:
+         * <ul>
+         *     <li>{@link VanishState#invisible()} = {@code false}</li>
+         *     <li>{@link VanishState#affectsMonsterSpawning()} = {@code true}</li>
+         *     <li>{@link VanishState#untargetable()} = {@code false}</li>
+         *     <li>{@link VanishState#createsSounds()} = {@code true}</li>
+         *     <li>{@link VanishState#createsParticles()} = {@code true}</li>
+         *     <li>{@link VanishState#triggerVibrations()} = {@code false}</li>
+         * </ul>
+         *
+         * @return A newly created visible {@link VanishState}
+         */
+        VanishState unvanished();
+    }
+}

src/main/java/org/spongepowered/api/entity/Entity.java

@@ -33,6 +33,7 @@
 import org.spongepowered.api.data.value.ListValue;
 import org.spongepowered.api.data.value.SetValue;
 import org.spongepowered.api.data.value.Value;
+import org.spongepowered.api.effect.VanishState;
 import org.spongepowered.api.event.cause.entity.damage.source.DamageSource;
 import org.spongepowered.api.projectile.source.EntityProjectileSource;
 import org.spongepowered.api.util.AABB;
@@ -75,6 +76,7 @@
  *
  * <p>Blocks and items (when they are in inventories) are not entities.</p>
  */
+@SuppressWarnings("deprecation")
 @DoNotStore
 public interface Entity extends Identifiable, HoverEventSource<HoverEvent.ShowEntity>, Locatable, EntityProjectileSource, Sound.Emitter,
         SerializableDataHolder.Mutable, RandomProvider {
@@ -325,8 +327,8 @@ default Collection<? extends Entity> nearbyEntities(final double distance, final
      */
     default boolean canSee(final Entity entity) {
         Objects.requireNonNull(entity, "Entity cannot be null");
-        final Optional<Boolean> optional = entity.get(Keys.VANISH);
-        return !optional.isPresent() || !optional.get();
+        final Optional<VanishState> optional = entity.get(Keys.VANISH_STATE);
+        return !optional.map(VanishState::invisible).orElse(false);
     }
 
     /**
@@ -606,10 +608,20 @@ default SetValue.Mutable<String> scoreboardTags() {
         return this.requireValue(Keys.SCOREBOARD_TAGS).asMutable();
     }
 
+    /**
+     * {@link Keys#VANISH_STATE}
+     *
+     * @return The current vanish state of the entity
+     */
+    default Value.Mutable<VanishState> vanishState() {
+        return this.requireValue(Keys.VANISH_STATE).asMutable();
+    }
+
     /**
      * {@link Keys#VANISH}
      *
      * @return Whether the entity is vanished
+     * @deprecated Use {@link #vanishState() VanishState} instead
      */
     default Value.Mutable<Boolean> vanish() {
         return this.requireValue(Keys.VANISH).asMutable();
@@ -619,6 +631,7 @@ default Value.Mutable<Boolean> vanish() {
      * {@link Keys#VANISH_IGNORES_COLLISION}
      *
      * @return Whether the entity ignores collision with other entities
+     * @deprecated Use {@link #vanishState()} instead
      */
     default Value.Mutable<Boolean> vanishIgnoresCollision() {
         return this.requireValue(Keys.VANISH_IGNORES_COLLISION).asMutable();
@@ -628,6 +641,7 @@ default Value.Mutable<Boolean> vanishIgnoresCollision() {
      * {@link Keys#VANISH_PREVENTS_TARGETING}
      *
      * @return Whether the entity can be targeted for attack by another entity
+     * @deprecated Use {@link #vanishState()} instead
      */
     default Value.Mutable<Boolean> vanishPreventsTargeting() {
         return this.requireValue(Keys.VANISH_PREVENTS_TARGETING).asMutable();