fix: update outdated paper references to legacy and add modern section

.github/workflows/gradle.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 17
+          java-version: 21
       - uses: gradle/gradle-build-action@v2
         with:
           # allow master and *-dev branches to write caches (default is only master/main)

code/build.gradle.kts

@@ -7,15 +7,17 @@ dependencies {
 
   // Minecraft
   implementation(libs.cloud.minecraft.extras)
+  implementation(libs.cloud.minecraft.paper)
+  implementation(libs.paper)
 
   // Processors
   implementation(libs.cloud.processors.cooldown)
 }
 
 indra {
   javaVersions {
-    minimumToolchain(17)
-    target(17)
+    minimumToolchain(21)
+    target(21)
   }
 }
 

code/gradle/libs.versions.toml

@@ -5,10 +5,18 @@ cloud = "2.0.0-rc.2"
 cloudMinecraft = "2.0.0-beta.8"
 cloudProcessors = "1.0.0-beta.3"
 
+paper = "1.20.6-R0.1-SNAPSHOT"
+
 [plugins]
 indra = { id = "net.kyori.indra", version.ref = "indra" }
 
 [libraries]
 cloud-core = { group = "org.incendo", name = "cloud-core", version.ref = "cloud" }
+
+# Minecraft
 cloud-minecraft-extras = { group = "org.incendo", name = "cloud-minecraft-extras", version.ref = "cloudMinecraft" }
+cloud-minecraft-paper = { group = "org.incendo", name = "cloud-paper", version.ref = "cloudMinecraft" }
+paper = { group = "io.papermc.paper", name = "paper-api", version.ref = "paper" }
+
+# Processors
 cloud-processors-cooldown = { group = "org.incendo", name = "cloud-processors-cooldown", version.ref = "cloudProcessors" }

code/settings.gradle.kts

@@ -22,6 +22,9 @@ dependencyResolutionManagement {
       name = "dv8tion"
       mavenContent { releasesOnly() }
     }
+    maven("https://repo.papermc.io/repository/maven-public/") {
+      name = "papermc"
+    }
   }
 }
 

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

@@ -0,0 +1,63 @@
+package org.incendo.cloud.snippet.minecraft;
+
+import io.papermc.paper.command.brigadier.CommandSourceStack;
+import org.bukkit.command.CommandSender;
+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;
+
+public class PaperExample {
+
+  public void exampleLegacyNative(final @NonNull JavaPlugin yourPlugin) {
+    final ExecutionCoordinator<CommandSender> executionCoordinator = ExecutionCoordinator.simpleCoordinator();
+    // --8<-- [start:legacy_native]
+    LegacyPaperCommandManager<CommandSender> commandManager = LegacyPaperCommandManager.createNative(
+      yourPlugin, /* 1 */
+      executionCoordinator /* 2 */
+    );
+    // --8<-- [end:legacy_native]
+  }
+
+  public void exampleLegacyCustom(
+    final @NonNull JavaPlugin yourPlugin,
+    final @NonNull SenderMapper<CommandSender, YourSenderType> senderMapper
+  ) {
+    final ExecutionCoordinator<YourSenderType> executionCoordinator = ExecutionCoordinator.simpleCoordinator();
+    // --8<-- [start:legacy_custom]
+    LegacyPaperCommandManager<YourSenderType> commandManager = new LegacyPaperCommandManager<>(
+      yourPlugin, /* 1 */
+      executionCoordinator, /* 2 */
+      senderMapper /* 3 */
+    );
+    // --8<-- [end:legacy_custom]
+  }
+
+  public void exampleModernNative(final @NonNull JavaPlugin javaPlugin) {
+    final ExecutionCoordinator<CommandSourceStack> executionCoordinator = ExecutionCoordinator.simpleCoordinator();
+    // --8<-- [start:modern_native]
+    PaperCommandManager<CommandSourceStack> commandManager = PaperCommandManager.builder()
+      .executionCoordinator(executionCoordinator)
+      .buildOnEnable(javaPlugin);
+      // or: .buildBootstrapped(bootstrapContext);
+    // --8<-- [end:modern_native]
+  }
+
+  public void exampleModernCustom(
+    final @NonNull JavaPlugin javaPlugin,
+    final @NonNull SenderMapper<CommandSourceStack, YourSenderType> senderMapper
+  ) {
+    final ExecutionCoordinator<YourSenderType> executionCoordinator = ExecutionCoordinator.simpleCoordinator();
+    // --8<-- [start:modern_custom]
+    PaperCommandManager<YourSenderType> commandManager = PaperCommandManager.builder(senderMapper)
+      .executionCoordinator(executionCoordinator)
+      .buildOnEnable(javaPlugin);
+      // or: .buildBootstrapped(bootstrapContext);
+    // --8<-- [end:modern_custom]
+  }
+
+  public record YourSenderType() {
+  }
+}

docs/minecraft/paper.md

@@ -24,28 +24,30 @@ Cloud for Paper is available through [Maven Central](https://central.sonatype.co
 
 ## Usage
 
-`cloud-paper` has a command manager implementation called
-{{ javadoc("https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/PaperCommandManager.html", "PaperCommandManager") }}
-that can be created in two ways.
+`cloud-paper` has two different command manager implementations:
+
+- {{ javadoc("https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/PaperCommandManager.html", "PaperCommandManager") }}: Paper command API
+- {{ javadoc("https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/LegacyPaperCommandManager.html", "LegacyPaperCommandManager") }}: Legacy command API
+
+{{ javadoc("https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/PaperCommandManager.html", "PaperCommandManager") }} should be preferred
+when targeting Paper 1.20.6+ exclusively. The new manager allows registering commands at bootstrapping time in addition to `onEnable`,
+which allows for using those commands in datapack functions.
+
+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.
+
+### Legacy
+
+The legacy command manager can be instantiated in two different ways.
 
 With a custom sender type:
 
-```java
-PaperCommandManager<YourSenderType> commandManager = new PaperCommandManager<>(
-  yourPlugin, /* 1 */
-  executionCoordinator, /* 2 */
-  senderMapper /* 3 */
-);
-```
+{{ snippet("minecraft/PaperExample.java", section = "legacy_custom", title = "") }}
 
 Or, using Bukkit's {{ javadoc("https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandSender.html", "CommandSender") }}:
 
-```java
-PaperCommandManager<CommandSender> commandManager = PaperCommandManager.createNative(
-  yourPlugin, /* 1 */
-  executionCoordinator /* 2 */
-);
-```
+{{ snippet("minecraft/PaperExample.java", section = "legacy_native", title = "") }}
 
 1. You need to pass an instance of the plugin that is constructing the command manager. This is used to register
    the commands and the different event listeners.
@@ -55,16 +57,26 @@ PaperCommandManager<CommandSender> commandManager = PaperCommandManager.createNa
 3. The sender mapper is a two-way mapping between Bukkit's
    {{ javadoc("https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandSender.html", "CommandSender") }} and your custom sender type.
    Using {{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-core/latest/org/incendo/cloud/SenderMapper.html#identity()>", "SenderMapper.identity()") }}
-   is equivalent to the {{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/PaperCommandManager.html#createNative(org.bukkit.plugin.Plugin,org.incendo.cloud.execution.ExecutionCoordinator)>", "createNative") }}
+   is equivalent to the {{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/LegacyPaperCommandManager.html#createNative(org.bukkit.plugin.Plugin,org.incendo.cloud.execution.ExecutionCoordinator)>", "createNative") }}
    static factory method.
 
+### Modern
+
+The modern command manager is created using a builder. You may either use the native
+{{ javadoc("https://jd.papermc.io/paper/1.20.6/io/papermc/paper/command/brigadier/CommandSourceStack.html", "CommandSourceStack") }}:
+{{ snippet("minecraft/PaperExample.java", section = "modern_native", title = "") }}
+
+or a custom type:
+{{ snippet("minecraft/PaperExample.java", section = "modern_custom", title = "") }}
+
 ## Brigadier
 
 Paper exposes [Brigadier](https://github.com/mojang/brigadier), which means that you may use the features
-from [cloud-brigadier](brigadier.md) on Paper servers.
+from [cloud-brigadier](brigadier.md) on Paper servers. When using the modern Paper manager, you do not need to explicitly
+enable Brigadier.
 
-You may enable Brigadier mappings using
-{{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/PaperCommandManager.html#registerBrigadier()>", "PaperCommandManager#registerBrigadier()") }}.
+When using the legacy command manager you may enable Brigadier mappings using
+{{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/LegacyPaperCommandManager.html#registerBrigadier()>", "LegacyPaperCommandManager#registerBrigadier()") }}.
 You should make use of the
 capability system to make sure that Brigadier is available on the server your plugin is running on:
 
@@ -85,7 +97,7 @@ Paper allows for non-blocking suggestions. You are highly recommended to make us
 the argument parsers during suggestion generation which ideally should not take place on the main server thread.
 
 You may enable asynchronous completions using
-{{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/PaperCommandManager.html#registerAsynchronousCompletions()>", "PaperCommandManager#registerAsynchronousCompletions()") }}.
+{{ javadoc("<https://javadoc.io/doc/org.incendo/cloud-paper/latest/org/incendo/cloud/paper/LegacyPaperCommandManager.html#registerAsynchronousCompletions()>", "LegacyPaperCommandManager#registerAsynchronousCompletions()") }}.
 You should make use of the capability system to make sure that this is available on the server your plugin is running on:
 
 ```java