feat: finish all misc arguments

Author: MC-XiaoHei

docs/en/create-commands/arguments/types/chat/chat-preview.md

@@ -105,7 +105,7 @@ Because the `ChatArgument` and `AdventureChatArgument` can support entity select
 
 For execution, we do the same procedure, because the text that the user enters still has `&` characters that need to be converted into a component.
 
-**Using Adventure Chat API**
+#### Use Adventure Chat API
 
 :::tabs
 ===Java
@@ -114,7 +114,7 @@ For execution, we do the same procedure, because the text that the user enters s
 <<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/chat/ChatPreview.kt#chatPreviewAdventureExample
 :::
 
-**Using Legacy Chat API**
+#### Use Legacy Chat API
 
 :::tabs
 ===Java

docs/en/create-commands/arguments/types/misc/potion-arguments.md

@@ -0,0 +1,47 @@
+---
+order: 11
+authors:
+  - DerEchtePilz
+  - JorelAli
+  - willkroboth
+---
+
+# Potion effect arguments
+
+![An image of a potion argument with a list of potion effect suggestions](/images/arguments/potion.png)
+
+The `PotionEffectArgument` class represents Minecraft potion effects. When used, this argument is casted to Bukkit's `PotionEffectType` class, or alternatively a `NamespacedKey` object if the `PotionEffectArgument.NamespacedKey` argument is used to create a `PotionEffectArgument`.
+
+::::tip Example - Giving a player a potion effect
+
+Say we wanted to have a command that gives a player a potion effect. For this command, we'll use the following syntax:
+
+```mccmd
+/potion <target> <potion> <duration> <strength>
+```
+
+In this example, we utilize some of the other arguments that we've described earlier, such as the `PlayerArgument` and `TimeArgument`. Since duration for the `PotionEffect` constructor is in ticks, this is perfectly fit for the `TimeArgument`, which is represented in ticks.
+
+#### Use `PotionEffectArgument`
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/PotionArguments.java#potionEffectArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/PotionArguments.kt#potionEffectArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/PotionArguments.kt#potionEffectArgumentsExampleDSL
+:::
+
+#### Use `PotionEffectArgument.NamespacedKey`
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/PotionArguments.java#potionEffectArgumentsNamespacedKeyExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/PotionArguments.kt#potionEffectArgumentsNamespacedKeyExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/PotionArguments.kt#potionEffectArgumentsNamespacedKeyExampleDSL
+:::
+
+::::

docs/en/create-commands/arguments/types/misc/recipe-arguments.md

@@ -0,0 +1,55 @@
+---
+order: 12
+authors:
+  - DerEchtePilz
+  - JorelAli
+  - willkroboth
+---
+
+# Recipe arguments
+
+![A recipe argument command with the suggestions for Minecraft items](/images/arguments/recipe.png)
+
+The `RecipeArgument` class lets you retrieve Bukkit's `ComplexRecipe` object.
+
+::::tip Example - Giving a player the result of a recipe
+
+Say we want to give yourself the result of a specific recipe. Since Bukkit's `Recipe` class contains the `getResult()` method, we will use that in our example. We want to create the following command:
+
+```mccmd
+/giverecipe <recipe>
+```
+
+As such, we easily implement it by specifying the `RecipeArgument`, casting it and adding it to the player's inventory:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/RecipeArguments.java#getResultExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/RecipeArguments.kt#getResultExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/RecipeArguments.kt#getResultExampleDSL
+:::
+
+::::
+
+::::tip Example - Unlocking a recipe for a player
+
+In this example, we'll use the `ComplexRecipe`'s `getKey()` method to write an example to to unlock a recipe for a player. For this command, we'll use the following syntax:
+
+```mccmd
+/unlockrecipe <player> <recipe>
+```
+
+This is then implemented trivially as follows:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/RecipeArguments.java#getKeyExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/RecipeArguments.kt#getKeyExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/RecipeArguments.kt#getKeyExampleDSL
+:::
+
+::::

docs/en/create-commands/arguments/types/misc/sound-arguments.md

@@ -0,0 +1,63 @@
+---
+order: 13
+authors:
+  - DerEchtePilz
+  - JorelAli
+  - willkroboth
+---
+
+# Sound arguments
+
+![A sound argument command with a list of Minecraft sounds as suggestions](/images/arguments/sound.png)
+
+The `SoundArgument` class allows a command sender to retrieve the Bukkit `Sound` or `NamespacedKey` object to represent in-game sound effects (such as mob sounds or ambient sound effects), as well as in-game music.
+
+The `SoundArgument` can return a `Sound` or `NamespacedKey` object. To return a `Sound` object, simply use the `SoundArgument` as normal. To return a `NamespacedKey` object, use the `SoundArgument.NamespacedKey` constructor instead:
+
+```java
+// Makes a SoundArgument that returns a Sound
+new SoundArgument("sound");
+
+// Makes a SoundArgument that returns a NamespacedKey
+new SoundArgument.NamespacedKey("sound");
+```
+
+:::warning
+
+When using the `Sound` object, the CommandAPI will return `null` if the specified `Sound` could not be found. For this reason, it's recommended to use the `NamespacedKey` object for optimal compatibility with client-side resourcepacks.
+
+:::
+
+::::tip Example - Playing sound to yourself
+
+Say we want a simple command that plays a specific sound at your location. To do this, we will make the following command:
+
+```mccmd
+/sound <sound>
+```
+
+This command simply plays the provided sound to the current player:
+
+#### Use `SoundArgument`
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/SoundArguments.java#soundArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/SoundArguments.kt#soundArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/SoundArguments.kt#soundArgumentsExampleDSL
+:::
+
+#### Use `SoundArgument.NamespacedKey`
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/SoundArguments.java#soundArgumentsNamespacedKeyExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/SoundArguments.kt#soundArgumentsNamespacedKeyExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/SoundArguments.kt#soundArgumentsNamespacedKeyExampleDSL
+:::
+
+::::

docs/en/create-commands/arguments/types/misc/time-arguments.md

@@ -0,0 +1,40 @@
+---
+order: 14
+authors:
+  - DerEchtePilz
+  - JorelAli
+  - willkroboth
+---
+
+# Time arguments
+
+![A time argument with Minecraft suggestions 'd', 's' and 't'](/images/arguments/time.png)
+
+The `TimeArgument` class represents in-game time, _in the number of in-game ticks_. This allows command senders to specify a certain number of ticks in a simpler way, by including the characters `d` to specify the numbers of days, `s` to specify the number of seconds or `t` to specify a number of ticks.
+
+The CommandAPI converts the inputs provided by the command sender into a number of ticks as an integer.
+
+:::info
+
+The `TimeArgument` provides inputs such as `2d` (2 in-game days), `10s` (10 seconds) and `20t` (20 ticks), but does **not** let you combine them, such as `2d10s`.
+
+:::
+
+::::tip Example - Displaying a server-wide announcement
+
+Say we have a command `bigmsg` that displays a title message to all players for a certain duration:
+
+```mccmd
+/bigmsg <duration> <message>
+```
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/TimeArguments.java#timeArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/TimeArguments.kt#timeArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/TimeArguments.kt#timeArgumentsExampleDSL
+:::
+
+::::

docs/en/create-commands/arguments/types/misc/uuid-arguments.md

@@ -0,0 +1,9 @@
+---
+order: 15
+authors:
+  - JorelAli
+---
+
+# UUID arguments
+
+The UUID argument is used to uniquely identify players, entities and attribute modifiers. As a result, its cast type is Java's `UUID`.

docs/en/create-commands/arguments/types/misc/world-arguments.md

@@ -0,0 +1,34 @@
+---
+order: 16
+authors:
+  - DerEchtePilz
+  - JorelAli
+  - willkroboth
+---
+
+# World arguments
+
+![A picture of world arguments in action](/images/arguments/worldargument.png)
+
+The `WorldArgument` class allows a command sender to refer to a loaded Bukkit `World`.
+
+::::tip Example - Unloading world
+
+Say we want to unload a world on our Minecraft server. We want to create a command with the following syntax:
+
+```mccmd
+/unloadworld <world>
+```
+
+Using the world from the `WorldArgument`, we can then unload the world safely using `Bukkit.getServer().unloadWorld()` and passing `true` (to save chunks):
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/WorldArguments.java#worldArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/WorldArguments.kt#worldArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/WorldArguments.kt#worldArgumentsExampleDSL
+:::
+
+::::

reference-code/src/main/java/createcommands/arguments/types/misc/PotionArguments.java

@@ -0,0 +1,53 @@
+package createcommands.arguments.types.misc;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.IntegerArgument;
+import dev.jorel.commandapi.arguments.PlayerArgument;
+import dev.jorel.commandapi.arguments.PotionEffectArgument;
+import dev.jorel.commandapi.arguments.TimeArgument;
+import org.bukkit.NamespacedKey;
+import org.bukkit.entity.Player;
+import org.bukkit.potion.PotionEffect;
+import org.bukkit.potion.PotionEffectType;
+
+class PotionArguments {
+    {
+        // #region potionEffectArgumentsExample
+        new CommandAPICommand("potion")
+            .withArguments(new PlayerArgument("target"))
+            .withArguments(new PotionEffectArgument("potion"))
+            .withArguments(new TimeArgument("duration"))
+            .withArguments(new IntegerArgument("strength"))
+            .executes((sender, args) -> {
+                Player target = (Player) args.get("target");
+                PotionEffectType potion = (PotionEffectType) args.get("potion");
+                int duration = (int) args.get("duration");
+                int strength = (int) args.get("strength");
+
+                // Add the potion effect to the target player
+                target.addPotionEffect(new PotionEffect(potion, duration, strength));
+            })
+            .register();
+        // #endregion potionEffectArgumentsExample
+
+        // #region potionEffectArgumentsNamespacedKeyExample
+        new CommandAPICommand("potion")
+            .withArguments(new PlayerArgument("target"))
+            .withArguments(new PotionEffectArgument.NamespacedKey("potion"))
+            .withArguments(new TimeArgument("duration"))
+            .withArguments(new IntegerArgument("strength"))
+            .executes((sender, args) -> {
+                Player target = (Player) args.get("target");
+                NamespacedKey potionKey = (NamespacedKey) args.get("potion");
+                int duration = (int) args.get("duration");
+                int strength = (int) args.get("strength");
+
+                PotionEffectType potion = PotionEffectType.getByKey(potionKey);
+
+                // Add the potion effect to the target player
+                target.addPotionEffect(new PotionEffect(potion, duration, strength));
+            })
+            .register();
+        // #endregion potionEffectArgumentsNamespacedKeyExample
+    }
+}

reference-code/src/main/java/createcommands/arguments/types/misc/RecipeArguments.java

@@ -0,0 +1,34 @@
+package createcommands.arguments.types.misc;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.PlayerArgument;
+import dev.jorel.commandapi.arguments.RecipeArgument;
+import org.bukkit.entity.Player;
+import org.bukkit.inventory.ComplexRecipe;
+
+class RecipeArguments {
+    {
+        // #region getResultExample
+        new CommandAPICommand("giverecipe")
+            .withArguments(new RecipeArgument("recipe"))
+            .executesPlayer((player, args) -> {
+                ComplexRecipe recipe = (ComplexRecipe) args.get("recipe");
+                player.getInventory().addItem(recipe.getResult());
+            })
+            .register();
+        // #endregion getResultExample
+
+        // #region getKeyExample
+        new CommandAPICommand("unlockrecipe")
+            .withArguments(new PlayerArgument("player"))
+            .withArguments(new RecipeArgument("recipe"))
+            .executes((sender, args) -> {
+                Player target = (Player) args.get("player");
+                ComplexRecipe recipe = (ComplexRecipe) args.get("recipe");
+
+                target.discoverRecipe(recipe.getKey());
+            })
+            .register();
+        // #endregion getKeyExample
+    }
+}

reference-code/src/main/java/createcommands/arguments/types/misc/SoundArguments.java

@@ -0,0 +1,28 @@
+package createcommands.arguments.types.misc;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.SoundArgument;
+import org.bukkit.NamespacedKey;
+import org.bukkit.Sound;
+
+class SoundArguments {
+    {
+        // #region soundArgumentsExample
+        new CommandAPICommand("sound")
+            .withArguments(new SoundArgument("sound"))
+            .executesPlayer((player, args) -> {
+                player.getWorld().playSound(player.getLocation(), (Sound) args.get("sound"), 100.0f, 1.0f);
+            })
+            .register();
+        // #endregion soundArgumentsExample
+
+        // #region soundArgumentsNamespacedKeyExample
+        new CommandAPICommand("sound")
+            .withArguments(new SoundArgument.NamespacedKey("sound"))
+            .executesPlayer((player, args) -> {
+                player.getWorld().playSound(player.getLocation(), ((NamespacedKey) args.get("sound")).asString(), 100.0f, 1.0f);
+            })
+            .register();
+        // #endregion soundArgumentsNamespacedKeyExample
+    }
+}