feat(minecraft): improvements & simple sender mapper information (#45)

.gitignore

@@ -400,3 +400,6 @@ poetry.toml
 pyrightconfig.json
 
 # End of https://www.toptal.com/developers/gitignore/api/python,intellij+all,node
+
+# Project specific
+code/.gradle

code/gradle/libs.versions.toml

@@ -2,7 +2,7 @@
 indra = "3.1.3"
 
 cloud = "2.0.0-rc.2"
-cloudMinecraft = "2.0.0-beta.8"
+cloudMinecraft = "2.0.0-SNAPSHOT"
 cloudProcessors = "1.0.0-beta.3"
 
 paper = "1.20.6-R0.1-SNAPSHOT"

code/src/main/java/org/incendo/cloud/snippet/minecraft/PaperExample.java

@@ -2,12 +2,16 @@
 
 import io.papermc.paper.command.brigadier.CommandSourceStack;
 import org.bukkit.command.CommandSender;
+import org.bukkit.entity.Player;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.incendo.cloud.SenderMapper;
 import org.incendo.cloud.execution.ExecutionCoordinator;
 import org.incendo.cloud.paper.LegacyPaperCommandManager;
 import org.incendo.cloud.paper.PaperCommandManager;
+import org.incendo.cloud.paper.util.sender.PaperSimpleSenderMapper;
+import org.incendo.cloud.paper.util.sender.PlayerSource;
+import org.incendo.cloud.paper.util.sender.Source;
 
 public class PaperExample {
 
@@ -58,6 +62,28 @@ public void exampleModernCustom(
     // --8<-- [end:modern_custom]
   }
 
+  public void exampleModernSimpleSenderMapper(
+    final @NonNull JavaPlugin javaPlugin
+  ) {
+    final ExecutionCoordinator<Source> executionCoordinator = ExecutionCoordinator.simpleCoordinator();
+    // --8<-- [start:modern_simple_sender_mapper]
+    PaperCommandManager<Source> commandManager = PaperCommandManager
+      .builder(PaperSimpleSenderMapper.simpleSenderMapper())
+      .executionCoordinator(executionCoordinator)
+      .buildOnEnable(javaPlugin);
+      // or: .buildBootstrapped(bootstrapContext);
+
+      // this command will only be available to players, and the player type is directly available.
+      commandManager.command(commandManager.commandBuilder("player_command")
+        .senderType(PlayerSource.class)
+        .handler(context -> {
+          Player player = context.sender().source();
+          player.sendMessage("Hello, player!");
+        })
+      );
+    // --8<-- [end:modern_simple_sender_mapper]
+  }
+
   public record YourSenderType() {
   }
 }

docs/minecraft/brigadier.md

@@ -36,6 +36,11 @@ If the command manager is a `BrigadierManagerHolder`, then you can get the insta
 
 The `CloudBrigadierManager` is how you interact with Brigadier to register mappings and configure settings.
 
+!!! warning "Alias Registration"
+
+    Only aliases for root nodes will be registered when using Brigadier. Due to how it's command
+    tree works it can quickly become inflated when sub-commands have aliases.
+
 ### Settings
 
 `CloudBrigadierManager` has settings that can be accessed using `CloudBrigadierManager.settings()`.

docs/minecraft/paper.md

@@ -37,6 +37,11 @@ If the plugin is targeting older Paper versions or non-paper servers, then
 {{ javadoc("https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/LegacyPaperCommandManager.html", "LegacyPaperCommandManager") }}
 should be used.
 
+!!! tip "Plugin Configuration Files"
+
+    Do not register your commands in your plugin.yml or paper-plugin.yml, Cloud handles the registration
+    itself and doing it yourself will cause issues.
+
 ### Legacy
 
 The legacy command manager can be instantiated in two different ways.
@@ -132,3 +137,12 @@ if (commandManager.hasCapability(CloudBukkitCapabilities.NATIVE_BRIGADIER)) {
 ## Parsers
 
 `cloud-paper` has access to all the parsers from [cloud-bukkit](bukkit.md#parsers).
+
+## Provided Sender Mapper
+
+Cloud includes a built-in sender mapper designed for the command manager. Due to the CommandSourceStack having no exposed implementations it can be difficult to work,
+here's an example of creating a command manager with the sender mapper and using the provided mapped sender:
+
+{{ snippet("minecraft/PaperExample.java", section = "modern_simple_sender_mapper", title = "") }}
+
+This will give you access to Source with the included extensions: PlayerSource, ConsoleSource, EntitySource and GenericSource