Merge branch 'api-8' into api-9

Author: ImMorpheus

src/main/java/org/spongepowered/api/adventure/SpongeComponents.java

@@ -27,9 +27,6 @@
 import net.kyori.adventure.audience.Audience;
 import net.kyori.adventure.text.Component;
 import net.kyori.adventure.text.event.ClickEvent;
-import net.kyori.adventure.text.serializer.gson.GsonComponentSerializer;
-import net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer;
-import net.kyori.adventure.text.serializer.plain.PlainComponentSerializer;
 import org.spongepowered.api.Sponge;
 import org.spongepowered.api.command.CommandCause;
 import org.spongepowered.api.registry.DefaultedRegistryReference;
@@ -102,97 +99,13 @@ public static Component resolve(
         return SpongeComponents.factory().render(component, senderContext, resolver, otherResolvers);
     }
 
-    /**
-     * Get a serializer for {@link Component}s that will convert to and from the
-     * legacy component format used by the Vanilla client.
-     *
-     * <p>This legacy serializer uses the standard section symbol to mark
-     * formatting characters.</p>
-     *
-     * <p>Implementations may provide a serializer capable of processing any
-     * information that requires access to implementation details.</p>
-     *
-     * @return a section serializer
-     */
-    public static LegacyComponentSerializer legacySectionSerializer() {
-        return SpongeComponents.factory().legacySectionSerializer();
-    }
-
-    /**
-     * Get a serializer for {@link Component}s that will convert to and from the
-     * legacy component format used by the Vanilla client.
-     *
-     * <p>This legacy serializer uses the alternate ampersand symbol ({@code &})
-     * to mark formatting characters.</p>
-     *
-     * <p>Implementations may provide a serializer capable of processing any
-     * information that requires access to implementation details.</p>
-     *
-     * @return a legacy serializer using ampersands
-     */
-    public static LegacyComponentSerializer legacyAmpersandSerializer() {
-        return SpongeComponents.factory().legacyAmpersandSerializer();
-    }
-
-    /**
-     * Get a serializer for {@link Component}s that will convert to and from the
-     * legacy component format used by the Vanilla client.
-     *
-     * <p>Implementations may provide a serializer capable of processing any
-     * information that requires access to implementation details.</p>
-     *
-     * @param formatChar the format character to use in place of the standard
-     *         section symbol
-     * @return a legacy serializer using ampersands
-     */
-    public static LegacyComponentSerializer legacySerializer(final char formatChar) {
-        return SpongeComponents.factory().legacySerializer(formatChar);
-    }
-
-    /**
-     * Get a serializer for {@link Component}s that will convert to and from the
-     * standard JSON serialization format using Gson.
-     *
-     * <p>Implementations may provide a serializer capable of processing any
-     * information that requires implementation details, such as legacy
-     * (pre-1.16) hover events.</p>
-     *
-     * @return a json component serializer
-     */
-    public static GsonComponentSerializer gsonSerializer() {
-        return SpongeComponents.factory().gsonSerializer();
-    }
-
-    /**
-     * Get a serializer for {@link Component}s that will convert components to
-     * a plain-text string.
-     *
-     * <p>Implementations may provide a serializer capable of processing any
-     * information that requires access to implementation details.</p>
-     *
-     * @return a serializer to plain text
-     */
-    public static PlainComponentSerializer plainSerializer() {
-        return SpongeComponents.factory().plainSerializer();
-    }
-
     private static Factory factory() {
         return Sponge.game().factoryProvider().provide(Factory.class);
     }
 
     public interface Factory {
         ClickEvent callbackClickEvent(final Consumer<CommandCause> callback);
 
-        LegacyComponentSerializer legacySectionSerializer();
-
-        LegacyComponentSerializer legacyAmpersandSerializer();
-
-        LegacyComponentSerializer legacySerializer(final char formatChar);
-
-        GsonComponentSerializer gsonSerializer();
-
-        PlainComponentSerializer plainSerializer();
-
         @SuppressWarnings("unchecked")
         Component render(
             final Component component,

src/main/java/org/spongepowered/api/command/Command.java

@@ -39,11 +39,13 @@
 import org.spongepowered.api.event.Cause;
 import org.spongepowered.api.event.EventContext;
 import org.spongepowered.api.event.lifecycle.RegisterCommandEvent;
+import org.spongepowered.api.service.permission.PermissionDescription;
 import org.spongepowered.api.service.permission.Subject;
 
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
+import java.util.Objects;
 import java.util.Optional;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -555,6 +557,31 @@ default Builder shortDescription(@Nullable final Component description) {
          */
         Builder permission(@Nullable String permission);
 
+        /**
+         * The permission that the responsible {@link Subject} in the given
+         * {@link Cause} requires to run this command.
+         *
+         * <p>For more control over whether a command can be executed, use
+         * {@link #executionRequirements(Predicate)}. However, note that
+         * setting a permission here will not override anything set in
+         * {@link #executionRequirements(Predicate)}, both will be checked
+         * during execution.</p>
+         *
+         * <p>Any permission checks set here will be performed during the
+         * {@link Command#canExecute(CommandCause)}.</p>
+         *
+         * <p>Calling this repeatedly will not add additional permission
+         * checks, instead replacing the permission check. If multiple
+         * permission checks are required, use
+         * {@link #executionRequirements(Predicate)}.</p>
+         *
+         * @param permission The description for the required permission.
+         * @return This builder, for chaining
+         */
+        default Builder permission(PermissionDescription permission) {
+            return this.permission(Objects.requireNonNull(permission, "permission").id());
+        }
+
         /**
          * Sets a function that determines what is required of the provided
          * {@link Cause} before this command executes. Calling this method

src/main/java/org/spongepowered/api/command/CommandCause.java

@@ -125,6 +125,11 @@ static CommandCause create() {
      */
     Cause cause();
 
+    @Override
+    default Cause contextCause() {
+        return this.cause();
+    }
+
     /**
      * @see Cause#context()
      *
@@ -250,6 +255,9 @@ default List<Object> all() {
      *    </li>
      * </ul>
      *
+     * <p>This subject may present a different view of default context than
+     * calls to {@link Subject} methods directly on this cause.</p>
+     *
      * <p><strong>Note:</strong> while it might be tempting to use this as the
      * invoker of the command, the {@link Cause#root()} and this might be
      * different. Command executors should generally use the root of the

src/main/java/org/spongepowered/api/command/parameter/Parameter.java

@@ -65,6 +65,7 @@
 import org.spongepowered.api.world.server.ServerLocation;
 import org.spongepowered.api.world.server.ServerWorld;
 import org.spongepowered.configurate.util.Types;
+import org.spongepowered.math.vector.Vector2d;
 import org.spongepowered.math.vector.Vector3d;
 import org.spongepowered.plugin.PluginContainer;
 
@@ -618,6 +619,16 @@ static Parameter.Value.Builder<ResourceKey> resourceKey() {
         return Parameter.builder(ResourceKey.class, ResourceKeyedValueParameters.RESOURCE_KEY);
     }
 
+    /**
+     * Creates a builder that has the {@link ValueParameter} set to
+     * {@link ResourceKeyedValueParameters#ROTATION}.
+     *
+     * @return A {@link Parameter.Value.Builder}
+     */
+    static Parameter.Value.Builder<Vector3d> rotation() {
+        return Parameter.builder(Vector3d.class, ResourceKeyedValueParameters.ROTATION);
+    }
+
     /**
      * Creates a builder that has the {@link ValueParameter} set to
      * {@link ResourceKeyedValueParameters#STRING}.

src/main/java/org/spongepowered/api/command/parameter/managed/standard/ResourceKeyedValueParameters.java

@@ -296,6 +296,28 @@ public final class ResourceKeyedValueParameters {
      */
     public static final DefaultedRegistryReference<ResourceKeyedValueParameter<ResourceKey>> RESOURCE_KEY = ResourceKeyedValueParameters.key(ResourceKey.sponge("resource_key"));
 
+    /**
+     * Require an argument to be a {@link Vector3d}, where any relative value
+     * (i.e. anything specified using tilde (~) notation) will be based on the
+     * invoker's current rotation.
+     *
+     * <p>The supplied {@link Vector2d} will contain the Euler components
+     * (yaw, pitch, roll), where:</p>
+     *
+     * <ul>
+     *     <li>the angles are specified in degrees;</li>
+     *     <li>(0, 0) is looking directly south, parallel to the x-z plane;</li>
+     *     <li>the yaw is measured as the angle counter-clockwise from due south
+     *     in the x-z plane; and</li>
+     *     <li>the pitch is negative when rotating up from the x-z plane.</li>
+     *     <li>the roll is zero</li>
+     * </ul>
+     *
+     * <p>This is presented as a {@link Vector3d} even though only two arguments
+     * are parsed for consistency with {@link Entity#rotation()}.</p>
+     */
+    public static final DefaultedRegistryReference<ResourceKeyedValueParameter<Vector3d>> ROTATION = ResourceKeyedValueParameters.key(ResourceKey.sponge("rotation"));
+
     /**
      * Require an argument to be a string.
      *

src/main/java/org/spongepowered/api/entity/living/player/server/ServerPlayer.java

@@ -50,7 +50,7 @@
 import org.spongepowered.api.resourcepack.ResourcePack;
 import org.spongepowered.api.scoreboard.Scoreboard;
 import org.spongepowered.api.service.permission.Subject;
-import org.spongepowered.api.world.WorldBorder;
+import org.spongepowered.api.world.border.WorldBorder;
 import org.spongepowered.api.world.server.ServerWorld;
 import org.spongepowered.plugin.PluginContainer;
 
@@ -239,20 +239,30 @@ default SetValue.Mutable<SkinPart> displayedSkinParts() {
 
     /**
      * Gets the {@link WorldBorder} for this player, if present. If no border is
-     * set, {@link Optional#empty()} is returned.
+     * set, an empty {@code Optional} is returned.
      *
      * @return The {@code WorldBorder} of this player as an {@code Optional}, if
      *     present
      */
     Optional<WorldBorder> worldBorder();
 
     /**
-     * Sets the {@link WorldBorder} instance for this player to the given world
-     * border. If {@code null} is passed, the world border is unset.
+     * Sets the {@link WorldBorder} that this player sees. If {@code null}, the
+     * border is unset, reverting to the border of the world the player is
+     * currently in.
+     *
+     * <p>The values that are set may be altered by events, so users should
+     * check the returned value if they need to know if an event altered the
+     * values in some way. If no alterations were made, the supplied object
+     * and the returned object (within the optional) will be the same.</p>
      *
      * @param border The world border to be used, may be {@code null}
+     * @return the values that were actually set, which may be different
+     *         from those requested. If the result is an empty optional,
+     *         then the player does not have a personal border, and uses
+     *         that of the world they are in instead.
      */
-    void setWorldBorder(@Nullable WorldBorder border);
+    Optional<WorldBorder> setWorldBorder(@Nullable WorldBorder border);
 
     /**
      * Gets the {@link CooldownTracker} for this player, allowing control

src/main/java/org/spongepowered/api/event/action/LightningEvent.java

@@ -28,11 +28,25 @@
 import org.spongepowered.api.event.Event;
 import org.spongepowered.api.event.entity.AffectEntityEvent;
 
+/**
+ * Base event for {@link org.spongepowered.api.entity.EntityTypes#LIGHTNING_BOLT}s.
+ */
 public interface LightningEvent extends Event {
 
+    /**
+     * Fires before a lightning strike happens.
+     * <p>Cancelling this completely prevents the lightning at its effects.</p>
+     */
     interface Pre extends LightningEvent, Cancellable {}
 
+    /**
+     * Fires when a lightning strike happens.
+     * <p>The affected entities can be modified.</p>
+     */
     interface Strike extends LightningEvent, AffectEntityEvent {}
 
+    /**
+     * Fires after a lightning strike happened.
+     */
     interface Post extends LightningEvent {}
 }