Adds WorldArgument for #358

Extra thanks to @booky10 for their help with cracking this one!

commandapi-annotations/src/main/java/dev/jorel/commandapi/annotations/arguments/AWorldArgument.java

@@ -0,0 +1,37 @@
+/*******************************************************************************
+ * Copyright 2022 Jorel Ali (Skepter) - MIT License
+ *
+ * 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 dev.jorel.commandapi.annotations.arguments;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import dev.jorel.commandapi.arguments.WorldArgument;
+
+/**
+ * Annotation equivalent of the {@link WorldArgument}
+ */
+@Primitive("org.bukkit.World")
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.PARAMETER)
+public @interface AWorldArgument {
+}

commandapi-core/src/main/java/dev/jorel/commandapi/arguments/CommandAPIArgumentType.java

@@ -91,6 +91,11 @@ public enum CommandAPIArgumentType {
 	 * The CustomArgument
 	 */
 	CUSTOM,
+
+	/**
+	 * The DimensionArgument
+	 */
+	DIMENSION("minecraft:dimension"),
 
 	/**
 	 * The EnchantmentArgument
@@ -111,7 +116,7 @@ public enum CommandAPIArgumentType {
 	/**
 	 * The EnvironmentArgument
 	 */
-	ENVIRONMENT("minecraft:dimension"),
+	ENVIRONMENT("api:environment"),
 
 	/**
 	 * The FloatRangeArgument

commandapi-core/src/main/java/dev/jorel/commandapi/arguments/EnvironmentArgument.java

@@ -32,15 +32,21 @@
 
 /**
  * An argument that represents the Bukkit Environment object
+ * 
+ * @deprecated Use {@link WorldArgument} instead.
  */
+@Deprecated
 public class EnvironmentArgument extends SafeOverrideableArgument<Environment, Environment> {
 
 	/**
 	 * An Environment argument. Represents Bukkit's Environment object
 	 * @param nodeName the name of the node for this argument
+	 * 
+	 * @deprecated Use {@link WorldArgument#WorldArgument(String)} instead.
 	 */
+	@Deprecated
 	public EnvironmentArgument(String nodeName) {
-		super(nodeName, CommandAPIHandler.getInstance().getNMS()._ArgumentDimension(), ((Function<Environment, String>) Environment::name).andThen(String::toLowerCase));
+		super(nodeName, CommandAPIHandler.getInstance().getNMS()._ArgumentEnvironment(), ((Function<Environment, String>) Environment::name).andThen(String::toLowerCase));
 	}
 
 	@Override
@@ -56,6 +62,6 @@ public CommandAPIArgumentType getArgumentType() {
 	@Override
 	public <CommandListenerWrapper> Environment parseArgument(NMS<CommandListenerWrapper> nms,
 			CommandContext<CommandListenerWrapper> cmdCtx, String key, Object[] previousArgs) throws CommandSyntaxException {
-		return nms.getDimension(cmdCtx, key);
+		return nms.getEnvironment(cmdCtx, key);
 	}
 }

commandapi-core/src/main/java/dev/jorel/commandapi/arguments/WorldArgument.java

@@ -0,0 +1,66 @@
+/*******************************************************************************
+ * Copyright 2022 Jorel Ali (Skepter) - MIT License
+ *
+ * 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 dev.jorel.commandapi.arguments;
+
+import java.util.function.Function;
+
+import org.bukkit.World;
+
+import com.mojang.brigadier.context.CommandContext;
+import com.mojang.brigadier.exceptions.CommandSyntaxException;
+
+import dev.jorel.commandapi.CommandAPIHandler;
+import dev.jorel.commandapi.nms.NMS;
+
+/**
+ * An argument that represents the Bukkit World object
+ */
+public class WorldArgument extends SafeOverrideableArgument<World, World> {
+
+	/**
+	 * A World argument. Represents Bukkit's World object
+	 * 
+	 * @param nodeName the name of the node for this argument
+	 */
+	public WorldArgument(String nodeName) {
+		super(nodeName, CommandAPIHandler.getInstance().getNMS()._ArgumentDimension(), ((Function<World, String>) World::getName).andThen(String::toLowerCase));
+	}
+
+	@Override
+	public Class<World> getPrimitiveType() {
+		return World.class;
+	}
+
+	@Override
+	public CommandAPIArgumentType getArgumentType() {
+		// We're keeping this underlying internal name as Dimension. The only thing
+		// that differs is the name of this class which is "WorldArgument", because
+		// the CommandAPI argument class names represent Bukkit objects wherever
+		// possible
+		return CommandAPIArgumentType.DIMENSION;
+	}
+
+	@Override
+	public <CommandListenerWrapper> World parseArgument(NMS<CommandListenerWrapper> nms,
+		CommandContext<CommandListenerWrapper> cmdCtx, String key, Object[] previousArgs) throws CommandSyntaxException {
+		return nms.getDimension(cmdCtx, key);
+	}
+}

commandapi-core/src/main/java/dev/jorel/commandapi/exceptions/UnimplementedArgumentException.java

@@ -0,0 +1,35 @@
+/*******************************************************************************
+ * Copyright 2022 Jorel Ali (Skepter) - MIT License
+ *
+ * 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 dev.jorel.commandapi.exceptions;
+
+/**
+ * An exception caused when using an argument which hasn't been implemented in this Minecraft version
+ */
+public class UnimplementedArgumentException extends RuntimeException {
+
+	/**
+	 * Creates an EnvironmentArgumentException
+	 */
+	public UnimplementedArgumentException(String type, String versionSupportedIn) {
+		super("The " + type + " is only compatible with Minecraft " + versionSupportedIn + " or later");
+	}
+
+}

commandapi-core/src/main/java/dev/jorel/commandapi/nms/NMS.java

@@ -30,7 +30,6 @@
 import java.util.function.Function;
 import java.util.function.Predicate;
 
-import com.mojang.brigadier.Message;
 import org.bukkit.Axis;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
@@ -58,6 +57,7 @@
 import org.bukkit.potion.PotionEffectType;
 
 import com.mojang.brigadier.CommandDispatcher;
+import com.mojang.brigadier.Message;
 import com.mojang.brigadier.arguments.ArgumentType;
 import com.mojang.brigadier.context.CommandContext;
 import com.mojang.brigadier.exceptions.CommandSyntaxException;
@@ -96,6 +96,8 @@ public interface NMS<CommandListenerWrapper> {
 
 	ArgumentType<?> _ArgumentDimension();
 
+	ArgumentType<?> _ArgumentEnvironment();
+
 	ArgumentType<?> _ArgumentEnchantment();
 
 	ArgumentType<?> _ArgumentEntity(EntitySelector selector);
@@ -232,7 +234,9 @@ Predicate<Block> getBlockPredicate(CommandContext<CommandListenerWrapper> cmdCtx
 	 */
 	CommandSender getCommandSenderFromCSS(CommandListenerWrapper clw);
 
-	Environment getDimension(CommandContext<CommandListenerWrapper> cmdCtx, String key) throws CommandSyntaxException;
+	World getDimension(CommandContext<CommandListenerWrapper> cmdCtx, String key) throws CommandSyntaxException;
+
+	Environment getEnvironment(CommandContext<CommandListenerWrapper> cmdCtx, String key) throws CommandSyntaxException;
 
 	Enchantment getEnchantment(CommandContext<CommandListenerWrapper> cmdCtx, String key);
 

commandapi-core/src/test/java/Examples.java

@@ -31,7 +31,6 @@
 import java.util.concurrent.ThreadLocalRandom;
 import java.util.function.Predicate;
 
-import com.mojang.brigadier.Message;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.Chunk;
@@ -80,6 +79,7 @@
 import org.bukkit.scoreboard.Team;
 import org.bukkit.util.EulerAngle;
 
+import com.mojang.brigadier.Message;
 import com.mojang.brigadier.ParseResults;
 import com.mojang.brigadier.builder.ArgumentBuilder;
 import com.mojang.brigadier.context.StringRange;
@@ -149,6 +149,7 @@
 import dev.jorel.commandapi.arguments.TeamArgument;
 import dev.jorel.commandapi.arguments.TextArgument;
 import dev.jorel.commandapi.arguments.TimeArgument;
+import dev.jorel.commandapi.arguments.WorldArgument;
 import dev.jorel.commandapi.exceptions.WrapperCommandSyntaxException;
 import dev.jorel.commandapi.executors.ExecutorType;
 import dev.jorel.commandapi.wrappers.FunctionWrapper;
@@ -690,6 +691,20 @@ void chatarguments() {
 /* ANCHOR_END: environmentarguments */
 }
 
+{
+/* ANCHOR: worldarguments */
+new CommandAPICommand("unloadworld")
+    .withArguments(new WorldArgument("world"))
+    .executes((sender, args) -> {
+        World world = (World) args[0];
+
+        // Unload the world (and save the world's chunks)
+        Bukkit.getServer().unloadWorld(world, true);
+    })
+    .register();
+/* ANCHOR_END: worldarguments */
+}
+
 {
 /* ANCHOR: itemstackarguments */
 new CommandAPICommand("item")

commandapi-core/src/test/kotlin/Examples.kt

@@ -659,6 +659,20 @@ CommandAPICommand("createworld")
 /* ANCHOR_END: environmentarguments */
 }
 
+fun worldarguments() {
+/* ANCHOR: worldarguments */
+new CommandAPICommand("unloadworld")
+    .withArguments(WorldArgument("world"))
+    .executes(CommandExecutor { sender, args ->
+        val world = args[0] as World
+
+        // Unload the world (and save the world's chunks)
+        Bukkit.getServer().unloadWorld(world, true)
+    })
+    .register()
+/* ANCHOR_END: worldarguments */
+}
+
 fun itemstackarguments() {
 /* ANCHOR: itemstackarguments */
 CommandAPICommand("item")

commandapi-nms/commandapi-1.13.1/src/main/java/dev/jorel/commandapi/nms/NMS_1_13_1.java

@@ -16,7 +16,6 @@
 import java.util.function.Predicate;
 import java.util.function.ToIntFunction;
 
-import com.mojang.brigadier.Message;
 import org.bukkit.Axis;
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
@@ -62,6 +61,7 @@
 import org.bukkit.inventory.Recipe;
 import org.bukkit.potion.PotionEffectType;
 
+import com.mojang.brigadier.Message;
 import com.mojang.brigadier.arguments.ArgumentType;
 import com.mojang.brigadier.context.CommandContext;
 import com.mojang.brigadier.exceptions.CommandSyntaxException;
@@ -75,6 +75,7 @@
 import dev.jorel.commandapi.exceptions.BiomeArgumentException;
 import dev.jorel.commandapi.exceptions.TimeArgumentException;
 import dev.jorel.commandapi.exceptions.UUIDArgumentException;
+import dev.jorel.commandapi.exceptions.UnimplementedArgumentException;
 import dev.jorel.commandapi.preprocessor.Differs;
 import dev.jorel.commandapi.preprocessor.NMSMeta;
 import dev.jorel.commandapi.preprocessor.RequireField;
@@ -244,12 +245,18 @@ public ArgumentType<?> _ArgumentChatFormat() {
 		return ArgumentChatFormat.a();
 	}
 
-	@Differs(from = "1.13", by = "Not throwing EnvironmentArgumentException")
+	@Differs(from = "1.13", by = "Not throwing UnimplementedArgumentException")
 	@Override
 	public ArgumentType<?> _ArgumentDimension() {
 		return ArgumentDimension.a();
 	}
 
+	@Differs(from = "1.13", by = "Not throwing EnvironmentArgumentException")
+	@Override
+	public ArgumentType<?> _ArgumentEnvironment() {
+		return ArgumentDimension.a();
+	}
+
 	@Override
 	public ArgumentType<?> _ArgumentEnchantment() {
 		return ArgumentEnchantment.a();
@@ -558,9 +565,15 @@ public CommandSender getCommandSenderFromCSS(CommandListenerWrapper clw) {
 		}
 	}
 
-	@Differs(from = "1.13", by = "Implements getDimension for EnvironmentArgument")
+	@Differs(from = "1.13", by = "Implements getDimension for DimensionArgument")
+	@Override
+	public World getDimension(CommandContext<CommandListenerWrapper> cmdCtx, String key) {
+		return MINECRAFT_SERVER.getWorldServer(ArgumentDimension.a(cmdCtx, key)).getWorld();
+	}
+
+	@Differs(from = "1.13", by = "Implements getEnvironment for EnvironmentArgument")
 	@Override
-	public Environment getDimension(CommandContext<CommandListenerWrapper> cmdCtx, String key) {
+	public Environment getEnvironment(CommandContext<CommandListenerWrapper> cmdCtx, String key) {
 		DimensionManager manager = ArgumentDimension.a(cmdCtx, key);
 		return switch (manager.getDimensionID()) {
 			case 0 -> Environment.NORMAL;