feat: add more arguments

Author: MC-XiaoHei

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

@@ -0,0 +1,34 @@
+---
+order: 2
+authors:
+  - DerEchtePilz
+  - willkroboth
+  - JorelAli
+---
+
+# Advancement arguments
+
+![An advancement argument suggesting a list of Minecraft advancements](/images/arguments/advancement.png)
+
+The `AdvancementArgument` class represents in-game advancements. As expected, the `AdvancementArgument` can be casted to Bukkit's `Advancement` class.
+
+::::tip Example – Awarding a player an advancement
+
+Say we want to award a player an advancement. First, we need the syntax that our command will use:
+
+```mccmd
+/award <player> <advancement>
+```
+
+Since we require a player, we will use the `PlayerArgument` for this example. Given a player, we can simply get the `AdvancementProgress` for that player, and then award the criteria required to fully complete the provided advancement.
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/AdvancementArguments.java#advancementArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/AdvancementArguments.kt#advancementArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/AdvancementArguments.kt#advancementArgumentsExampleDSL
+:::
+
+::::

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

@@ -0,0 +1,23 @@
+---
+order: 1
+authors: 
+  - JorelAli
+---
+
+# Angle arguments
+
+The angle argument is used to represent the _yaw_ (horizontal) angle in degrees. The value returned from this argument range from -180.0 (inclusive) to 180 (exclusive), with -180.0 being due north:
+
+$$
+\begin{align}
+-1&80.0 \\\\
+&\hspace{0.1em}N \\\\
+&\uparrow \\\\
+90.0\ W \leftarrow &\hspace{0.75em}\rightarrow E\ -90.0 \\\\
+&\downarrow \\\\
+&\hspace{0.2em}S \\\\
+&0.0 \\\\
+\end{align}
+$$
+
+The `~` notation can be used to specify a rotation relative to the executor's yaw angle.

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

@@ -0,0 +1,56 @@
+---
+order: 3
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# Biome arguments
+
+![A biome argument suggesting a list of Minecraft biomes](/images/arguments/biome.png)
+
+In Minecraft 1.16, they added the ability to refer to in-game biomes. The CommandAPI implements this using the `BiomeArgument`. As expected, this returns Bukkit's `Biome` enum when used.
+
+:::warning
+
+When using the `Biome` object, the CommandAPI will return `null` if the specified `Biome` could not be found, for example if a player submitted a biome from a client-side resourcepack. The CommandAPI does **not** return `Biome.CUSTOM` from the `BiomeArgument`.
+
+:::
+
+::::tip Example – Setting the biome of a chunk
+
+Say you want to set the biome of the current chunk that a player is in. We can do this using the `World.setBiome(x, y, z, biome)` method for a given world. We will use this command syntax to set the biome of our current chunk:
+
+```mccmd
+/setbiome <biome>
+```
+
+And we can set the biome of the current chunk as expected:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/BiomeArguments.java#biomeArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/BiomeArguments.kt#biomeArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/BiomeArguments.kt#biomeArgumentsExampleDSL
+:::
+
+::::
+
+The `BiomeArgument` also supports returning a `NamespacedKey` for custom biomes. This can be done by using the `BiomeArgument.NamespacedKey` constructor instead of the normal `BiomeArgument` constructor:
+
+```java
+// Makes a BiomeArgument that returns a Biome
+new BiomeArgument("biome");
+
+// Makes a BiomeArgument that returns a NamespacedKey
+new BiomeArgument.NamespacedKey("biome");
+```
+
+:::info
+
+Spigot's support for custom biomes is really limited! If you have an example that lets you use custom biomes with namespaced keys, please open a GitHub issue, or reach out to us on Discord!
+
+:::

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

@@ -0,0 +1,40 @@
+---
+order: 4
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# BlockState arguments
+
+![A block state argument with suggestions for Minecraft items](/images/arguments/blockstate.png)
+
+The `BlockStateArgument` is used to represent data about blocks in the world. These refer to any blocks that have data or states, such as dispensers, signs, doors and pistons. The `BlockStateArgument` creates a Bukkit `BlockData` object when used.
+
+:::info
+
+Make sure to not confuse the cast type with `BlockState`. The naming of this argument refers to the internal Minecraft vanilla argument naming convention - **this argument casts to `BlockData` and NOT `BlockState`**.
+
+:::
+
+::::tip Example – Setting a block
+
+Say we want a simple command to set the block that you're looking at. We'll use the following command syntax:
+
+```mccmd
+/set <block>
+```
+
+And then we can simply set our block using `setBlockData()`:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/BlockStateArguments.java#blockStateArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/BlockStateArguments.kt#blockStateArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/BlockStateArguments.kt#blockStateArgumentsExampleDSL
+:::
+
+::::

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

@@ -0,0 +1,34 @@
+---
+order: 5
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# Enchantment arguments
+
+![An enchantment argument suggesting a list of Minecraft enchantments](/images/arguments/enchantment.png)
+
+The `EnchantmentArgument` class lets users input a specific enchantment. As you would expect, the cast type is Bukkit's `Enchantment` class.
+
+::::tip Example – Giving a player an enchantment on their current item
+
+Say we want to give a player an enchantment on the item that the player is currently holding. We will use the following command syntax:
+
+```mccmd
+/enchantitem <enchantment> <level>
+```
+
+Since most enchantment levels range between 1 and 5, we will also make use of the `IntegerArgument` to restrict the level of the enchantment by using its range constructor.
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/EnchantmentArguments.java#enchantmentArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/EnchantmentArguments.kt#enchantmentArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/EnchantmentArguments.kt#enchantmentArgumentsExampleDSL
+:::
+
+::::

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

@@ -0,0 +1,4 @@
+---
+order: 9
+title: Misc arguments
+---

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

@@ -0,0 +1,34 @@
+---
+order: 6
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# ItemStack arguments
+
+![An item stack argument with suggestions for Minecraft items](/images/arguments/itemstack.png)
+
+The `ItemStackArgument` class represents in-game items. As expected, this should be casted to Bukkit's `ItemStack` object. The `ItemStack` which is returned by the `ItemStackArgument` always has a size of 1.
+
+::::tip Example – Giving a player an itemstack
+
+Say we want to create a command that gives you items. For this command, we will use the following syntax:
+
+```mccmd
+/item <itemstack>
+```
+
+With this syntax, we can easily create our command:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/ItemStackArguments.java#itemStackArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/ItemStackArguments.kt#itemStackArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/ItemStackArguments.kt#itemStackArgumentsExampleDSL
+:::
+
+::::

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

@@ -0,0 +1,34 @@
+---
+order: 7
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# LootTable argument
+
+![A loot table argument showing a list of Minecraft loot tables as suggestions](/images/arguments/loottable.png)
+
+The `LootTableArgument` class can be used to get a Bukkit `LootTable` object.
+
+::::tip Example – Filling a chest with loot table contents
+
+Say we wanted to write a command that populates a chest with some loot table contents. For this example, we'll use the following command:
+
+```mccmd
+/giveloottable <loottable> <location>
+```
+
+We ensure that the location provided is a container (such as a chest or shulkerbox) and then update the contents of that container:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/misc/LootTableArguments.java#lootTableArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/LootTableArguments.kt#lootTableArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/misc/LootTableArguments.kt#lootTableArgumentsExampleDSL
+:::
+
+::::

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

@@ -0,0 +1,29 @@
+package createcommands.arguments.types.misc;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.AdvancementArgument;
+import dev.jorel.commandapi.arguments.PlayerArgument;
+import org.bukkit.advancement.Advancement;
+import org.bukkit.advancement.AdvancementProgress;
+import org.bukkit.entity.Player;
+
+class AdvancementArguments {
+    {
+        // #region advancementArgumentsExample
+        new CommandAPICommand("award")
+            .withArguments(new PlayerArgument("player"))
+            .withArguments(new AdvancementArgument("advancement"))
+            .executes((sender, args) -> {
+                Player target = (Player) args.get("player");
+                Advancement advancement = (Advancement) args.get("advancement");
+
+                // Award all criteria for the advancement
+                AdvancementProgress progress = target.getAdvancementProgress(advancement);
+                for (String criteria : advancement.getCriteria()) {
+                    progress.awardCriteria(criteria);
+                }
+            })
+            .register();
+        // #endregion advancementArgumentsExample
+    }
+}

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

@@ -0,0 +1,22 @@
+package createcommands.arguments.types.misc;
+
+import dev.jorel.commandapi.CommandAPICommand;
+import dev.jorel.commandapi.arguments.BiomeArgument;
+import org.bukkit.Chunk;
+import org.bukkit.block.Biome;
+
+class BiomeArguments {
+    {
+        // #region biomeArgumentsExample
+        new CommandAPICommand("setbiome")
+            .withArguments(new BiomeArgument("biome"))
+            .executesPlayer((player, args) -> {
+                Biome biome = (Biome) args.get("biome");
+
+                Chunk chunk = player.getLocation().getChunk();
+                player.getWorld().setBiome(chunk.getX(), player.getLocation().getBlockY(), chunk.getZ(), biome);
+            })
+            .register();
+        // #endregion biomeArgumentsExample
+    }
+}