feat: scoreboard arguments, entities arguments.

Author: MC-XiaoHei

docs/en/create-commands/arguments/types/entities-arguments.md

@@ -0,0 +1,137 @@
+---
+order: 7
+authors:
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+  - misode
+  - Strokkur424
+---
+
+# Entity & Player arguments
+
+## Entity selector argument
+
+![An image of an entity selector argument with a list of suggestions including entity selectors and a player name](/images/arguments/entityselector.png)
+
+Minecraft's [target selectors](https://minecraft.wiki/w/Commands#Target_selectors) (e.g. `@a` or `@e`) are implemented using the subclasses of the `EntitySelectorArgument` class. This allows you to select specific entities based on certain attributes.
+
+There are four `EntitySelectorArgument` subclasses that determine what type of data to return:
+
+- `EntitySelectorArgument.OneEntity` - A single entity, which returns a `Entity` object.
+- `EntitySelectorArgument.ManyEntities`  - A collection of many entities, which returns a `Collection<Entity>` object.
+- `EntitySelectorArgument.OnePlayer` - A single player, which returns a `Player` object.
+- `EntitySelectorArgument.ManyPlayers` - A collection of players, which returns a `Collection<Player>` object.
+
+The return type is the type to be cast when retrieved from the [`CommandArguments args`](../arguments) in the command declaration.
+
+::::tip Example - Remove entities command
+
+Say we want a command to remove certain types of entities. Typically, this would be implemented using a simple command like:
+
+```mccmd
+/remove <player>
+/remove <mob type>
+/remove <radius>
+```
+
+Instead, we can combine all of these into one by using the `EntitySelectorArgument`. We want to be able to target multiple entities at a time, so we want to use the `EntitySelectorArgument.ManyEntities` constructor. We can simply retrieve the `Collection<Entity>` from this argument and iteratively remove each entity:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/EntitiesArguments.java#entitySelectorArgumentExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/EntitiesArguments.kt#entitySelectorArgumentExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/EntitiesArguments.kt#entitySelectorArgumentExampleDSL
+:::
+
+We could then use this to target specific entities, for example:
+
+- To remove all cows:
+
+  ```mccmd
+  /remove @e[type=cow]
+  ```
+
+- To remove the 10 furthest pigs from the command sender:
+
+  ```mccmd
+  /remove @e[type=pig,limit=10,sort=furthest]
+  ```
+
+::::
+
+## Player argument
+
+The `PlayerArgument` class is very similar _(almost identical)_ to `EntitySelectorArgument.OnePlayer`. It returns a `Player` object and requires the player to be online.
+
+:::info
+The `PlayerArgument` internally uses the `GameProfile` class from Mojang's authlib, which means that this argument has a slight performance overhead compared to using `EntitySelectorArgument.OnePlayer`
+:::
+
+::::tip Example – PlayerArgument without entity selectors
+
+When registering a `PlayerArgument` you might notice that it includes `Entity Selectors` (`@a`, `@e`, `@r`, etc.). If you want to avoid those, you can use argument suggestions to only suggest the player names. For this example, let us create a /warp command:
+
+```mccmd
+/warp <player>
+```
+
+To get a `PlayerArgument` which only suggests the actual names, we can define it like this:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/EntitiesArguments.java#buildNoSelectorSuggestions
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/EntitiesArguments.kt#buildNoSelectorSuggestions
+:::
+
+Now we can define the rest of the command and include our suggestion inside it like this:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/EntitiesArguments.java#noSelectorSuggestionsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/EntitiesArguments.kt#noSelectorSuggestionsExample
+:::
+
+And there we have it! One thing to note is that entity selectors are still a valid input; they’re just not included in the suggestions.
+![WarpCommand](/images/entityselectorplayerexample.gif)
+
+::::
+
+## OfflinePlayer argument
+
+The `OfflinePlayerArgument` class is identical to the `PlayerArgument` class, but instead of returning a `Player` object, it returns an `OfflinePlayer` object. Internally, this argument makes calls to Mojang servers (via Mojang's authlib), meaning it can be slightly slower than alternative methods (such as using a `StringArgument` and suggesting a list of existing offline players).
+
+The `OfflinePlayerArgument` _should_ be able to retrieve players that have never joined the server before.
+
+## Entity type argument
+
+![An image of an entity argument displaying a list of entity type suggestions](/images/arguments/entitytype.png)
+
+The `EntityTypeArgument` class is used to retrieve a type of entity as defined in the [`EntityType`](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html) enum. In other words, this is an entity type, for example, a pig or a zombie.
+
+::::tip Example - Spawning entities
+
+Say we want a command to spawn a specific type of entity, similar to the `/summon` command in Vanilla Minecraft, with the addition of specifying how many entities to spawn. We want to create a command of the following form:
+
+```mccmd
+/spawnmob <entity> <amount>
+```
+
+Since we're trying to specify an entity type, we will use the `EntityTypeArgument` as our argument type for `<entity>`. We combine this with the `IntegerArgument` class with a specified range of $1 \le \textit{amount} \le 100$:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/EntitiesArguments.java#entityTypeArgumentExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/EntitiesArguments.kt#entityTypeArgumentExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/EntitiesArguments.kt#entityTypeArgumentExampleDSL
+:::
+
+Note how in this example above, we have to explicitly state `Player player, CommandArguments args`. This is due to a limitation of Java's type inference system which is discussed [here](../../registration#setting-the-commands-executor).
+
+::::

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

@@ -0,0 +1,4 @@
+---
+order: 8
+title: Scoreboard arguments
+---

docs/en/create-commands/arguments/types/scoreboard/objective-arguments.md

@@ -0,0 +1,62 @@
+---
+order: 2
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# Objective arguments
+
+In the CommandAPI, objectives are split into two classes:
+
+- The `ObjectiveArgument` class, which represents objectives as a whole
+- The `ObjectiveCriteriaArgument` class, which represents objective criteria
+
+## Objective argument
+
+The objective argument refers to a single scoreboard objective.
+
+::::tip Example – Move objective to sidebar
+
+As an example, let's create a command to move an objective to a player's sidebar. To do this, we will use the following command syntax:
+
+```mccmd
+/sidebar <objective>
+```
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/scoreboard/ObjectiveArguments.java#objectiveArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ObjectiveArguments.kt#objectiveArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ObjectiveArguments.kt#objectiveArgumentsExampleDSL
+:::
+
+::::
+
+## Objective criteria argument
+
+The `ObjectiveCriteriaArgument` is fairly straight forward - it represents the criteria for an objective. Similar to Bukkit, the objective criteria is simply represented as a `String`, so it must be casted to a `String` when being used.
+
+::::tip Example – Unregister all objectives by criteria
+
+Say we wanted to create a command to unregister all objectives based on a given criteria. Let's create a command with the following form:
+
+```mccmd
+/unregisterall <objective critera>
+```
+
+To do this, we're going to take advantage of Bukkit's `Scoreboard.getObjectivesByCriteria(String)` method
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/scoreboard/ObjectiveArguments.java#objectiveCriteriaArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ObjectiveArguments.kt#objectiveCriteriaArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ObjectiveArguments.kt#objectiveCriteriaArgumentsExampleDSL
+:::
+
+::::

docs/en/create-commands/arguments/types/scoreboard/scoreboard-arguments.md

@@ -0,0 +1,138 @@
+---
+order: 1
+authors:
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+  - misode
+---
+
+# Scoreboard arguments
+
+The CommandAPI uses two classes to provide information about a scoreboard:
+
+- The `ScoreHolderArgument` class represents **score holder** - a player's name or an entity's UUID that has scores in an objective. This is described in more detail [on the Minecraft Wiki](https://minecraft.wiki/w/Scoreboard#Objectives).
+- The `ScoreboardSlotArgument` class represents a **display slot** (sidebar, list or belowName) as well as the team color if the display is the sidebar. This is described in more detail [on the Minecraft Wiki](https://minecraft.wiki/w/Scoreboard#Display_slots).
+
+## Score holder argument
+
+The score holder argument can accept either a single entity or a collection of multiple entities. To specify which one to use, you must use the `ScoreHolderArgument.Single` or `ScoreHolderArgument.Multiple` constructor respectively:
+
+```java
+new ScoreHolderArgument.Single(nodeName);
+new ScoreHolderArgument.Multiple(nodeName);
+```
+
+Depending on which constructor is used, the cast type changes. If you use `ScoreHolderArgument.Single`, the argument must be cast to a `String`. Otherwise, if you use `ScoreHolderArgument.Multiple`, the argument must be cast to a `Collection<String>`.
+
+::::tip Example – Rewarding players with scoreboard objectives
+
+Say we want to reward all players that fit certain criteria. We want a command with the following syntax:
+
+```mccmd
+/reward <players>
+```
+
+Since we could have multiple players that fit a certain criterion, we want to use `ScoreHolderArgument.Multiple` constructor.
+
+To give this example a bit more context, let's say we want to reward all players that have died less than 10 times on the server. To do this, we will use the following command:
+
+```mccmd
+/reward @e[type=player,scores={deaths=..9}]
+```
+
+Note how we use `..9` to represent nine or fewer deaths (since ranges are inclusive). Also note how we restrict our input to players via the command using `type=player`. We can now implement our command:
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/scoreboard/ScoreboardArguments.java#scoreHolderArgumentExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ScoreboardArguments.kt#scoreHolderArgumentExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ScoreboardArguments.kt#scoreHolderArgumentExampleDSL
+:::
+
+::::
+
+:::info
+
+In the example above, we have our user use the `@e[type=player]` entity selector to restrict the `Collection<String>` so it only returns player names, which allows us to use `Bukkit.getPlayer(playerName)`. In practice, we can’t guarantee that such a selector will be used, so we could update the code to accept both entities and players. For example, we can differentiate between players and entities by using the `UUID.fromString(String)` method:
+
+```java
+Collection<String> entitiesAndPlayers = (Collection<String>) args.get(0);
+for(String str : entitiesAndPlayers) {
+    try {
+        UUID uuid = UUID.fromString(str);
+        // Is a UUID, so it must by an entity
+        Bukkit.getEntity(uuid);
+    } catch(IllegalArgumentException exception) {
+        // Not a UUID, so it must be a player name
+        Bukkit.getPlayer(str); 
+    }
+}
+```
+
+:::
+
+## Scoreboard slot argument
+
+![A scoreboardslotargument showing a list of suggestions of valid Minecraft scoreboard slot positions](/images/arguments/scoreboardslot.png)
+
+The `ScoreboardSlotArgument` represents where scoreboard information is displayed. Since the Bukkit scoreboard `DisplaySlot` is not able to represent the case where team colors are provided, the CommandAPI uses the `ScoreboardSlot` wrapper class as the representation of the `ScoreboardSlotArgument`.
+
+### `ScoreboardSlot` wrapper
+
+The `ScoreboardSlot` wrapper class has three main methods:
+
+```java
+enum ScoreboardSlot {
+    PLAYER_LIST,
+    SIDEBAR, // Unused, use the other SIDEBAR_TEAM_### values below
+    BELOW_NAME,
+    SIDEBAR_TEAM_BLACK,
+    SIDEBAR_TEAM_DARK_BLUE,
+    SIDEBAR_TEAM_DARK_GREEN,
+    SIDEBAR_TEAM_DARK_AQUA,
+    SIDEBAR_TEAM_DARK_RED,
+    SIDEBAR_TEAM_DARK_PURPLE,
+    SIDEBAR_TEAM_GOLD,
+    SIDEBAR_TEAM_GRAY,
+    SIDEBAR_TEAM_DARK_GRAY,
+    SIDEBAR_TEAM_BLUE,
+    SIDEBAR_TEAM_GREEN,
+    SIDEBAR_TEAM_AQUA,
+    SIDEBAR_TEAM_RED,
+    SIDEBAR_TEAM_LIGHT_PURPLE,
+    SIDEBAR_TEAM_YELLOW,
+    SIDEBAR_TEAM_WHITE;
+
+    public DisplaySlot getDisplaySlot();
+    public ChatColor getTeamColor();
+    public boolean hasTeamColor();
+
+    public NamespacedKey getKey();
+}
+```
+
+The `getDisplaySlot()` method returns the display slot that was chosen. Sidebar scoreboard colors can be accessed via `ScoreboardSlot.SIDEBAR_TEAM_###`. You can also retrieve the color using the `getTeamColor()` method.
+
+::::tip Example – Clearing objectives in a scoreboard slot
+
+Say we want to clear all objectives in a specific scoreboard slot. In this example, we will use the main server scoreboard, which is accessed using `Bukkit.getScoreboardManager.getMainScoreboard()`. We want a command with the following syntax:
+
+```mccmd
+/clearobjectives <slot>
+```
+
+We implement this simply by using the `ScoreboardSlotArgument` as our argument, and then we can clear the slot using the scoreboard `clearSlot(DisplaySlot)` method.
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/scoreboard/ScoreboardArguments.java#scoreboardSlotArgumentExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ScoreboardArguments.kt#scoreboardSlotArgumentExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/ScoreboardArguments.kt#scoreboardSlotArgumentExampleDSL
+:::
+
+::::

docs/en/create-commands/arguments/types/scoreboard/team-arguments.md

@@ -0,0 +1,32 @@
+---
+order: 3
+authors: 
+  - JorelAli
+  - DerEchtePilz
+  - willkroboth
+---
+
+# Team arguments
+
+The `TeamArgument` class interacts with the Minecraft scoreboard and represents a team.
+
+::::tip Example - Toggling friendly fire in a team
+
+Let's say we want to create a command to toggle the state of friendly fire in a team. We want a command of the following form
+
+```mccmd
+/togglepvp <team>
+```
+
+To do this, given a team we want to use the `setAllowFriendlyFire(boolean)` function.
+
+:::tabs
+===Java
+<<< @/../reference-code/src/main/java/createcommands/arguments/types/scoreboard/TeamArguments.java#teamArgumentsExample
+===Kotlin
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/TeamArguments.kt#teamArgumentsExample
+===Kotlin DSL
+<<< @/../reference-code/src/main/kotlin/createcommands/arguments/types/scoreboard/TeamArguments.kt#teamArgumentsExampleDSL
+:::
+
+::::