Bukkit/Paper improvements and reorganize cloud-minecraft-modded (#24)

Incendo · Jan 24, 2024 · 9ca084e · 9ca084e
1 parent ee76324
commit 9ca084e
Show file tree

Hide file tree

Showing 17 changed files with 97 additions and 86 deletions.
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,7 @@
 .idea/**/usage.statistics.xml
 .idea/**/dictionaries
 .idea/**/shelf
+.idea/**
 
 # AWS User-specific
 .idea/**/aws.xml
@@ -398,4 +399,4 @@ poetry.toml
 # LSP config files
 pyrightconfig.json
 
-# End of https://www.toptal.com/developers/gitignore/api/python,intellij+all,node
+# End of https://www.toptal.com/developers/gitignore/api/python,intellij+all,node
diff --git a/docs/annotations/index.md b/docs/annotations/index.md
@@ -12,7 +12,7 @@ Examples can be found on
 
 ## Installation
 
-Cloud Annotations is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud Annotations is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-annotations).
 
 <!-- prettier-ignore -->
 === "Maven"

diff --git a/docs/core/index.md b/docs/core/index.md
@@ -6,7 +6,7 @@ Generally you'll want to depend on a platform module which implements Cloud for
 
 ## Installation
 
-Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-core).
 
 <!-- prettier-ignore -->
 === "Maven"

diff --git a/docs/discord/discord4j.md b/docs/discord/discord4j.md
@@ -6,7 +6,7 @@ An example bot using cloud-discord4j can be found [here](https://github.com/Ince
 
 ## Installation
 
-Cloud for Discord4J is available through [Maven Central](https://search.maven.org/search?q=org.incendo).
+Cloud for Discord4J is available through [Maven Central](https://central.sonatype.com/artifact/org.incendo/cloud-discord4j).
 
 <!-- prettier-ignore -->
 === "Maven"

diff --git a/docs/discord/jda5.md b/docs/discord/jda5.md
@@ -6,7 +6,7 @@ An example bot using cloud-jda5 can be found [here](https://github.com/Incendo/c
 
 ## Installation
 
-Cloud for JDA5 is available through [Maven Central](https://search.maven.org/search?q=org.incendo).
+Cloud for JDA5 is available through [Maven Central](https://central.sonatype.com/artifact/org.incendo/cloud-jda5).
 
 <!-- prettier-ignore -->
 === "Maven"

diff --git a/docs/discord/kord.md b/docs/discord/kord.md
@@ -6,7 +6,7 @@ An example bot using cloud-kord can be found [here](https://github.com/Incendo/c
 
 ## Installation
 
-Cloud for Kord is available through [Maven Central](https://search.maven.org/search?q=org.incendo).
+Cloud for Kord is available through [Maven Central](https://central.sonatype.com/artifact/org.incendo/cloud-kord).
 
 <!-- prettier-ignore -->
 === "Maven"

diff --git a/docs/kotlin/annotations.md b/docs/kotlin/annotations.md
@@ -16,7 +16,7 @@ suspend fun yourCommand(
 
 ## Installation
 
-Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-kotlin-coroutines-annotations).
 
 <!-- prettier-ignore -->
 === "Gradle (Kotlin)"

diff --git a/docs/kotlin/coroutines.md b/docs/kotlin/coroutines.md
@@ -5,7 +5,7 @@ For suspending commands methods, see [cloud-kotlin-coroutines-annotations](./ann
 
 ## Installation
 
-Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-kotlin-coroutines).
 
 <!-- prettier-ignore -->
 === "Gradle (Kotlin)"

diff --git a/docs/kotlin/extensions.md b/docs/kotlin/extensions.md
@@ -4,7 +4,7 @@ This module contains extensions to different parts of Cloud.
 
 ## Installation
 
-Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-kotlin-extensions).
 
 <!-- prettier-ignore -->
 === "Gradle (Kotlin)"

diff --git a/docs/minecraft/bukkit.md b/docs/minecraft/bukkit.md
@@ -1,58 +1,8 @@
 # cloud-bukkit
 
-<!-- prettier-ignore -->
-!!! note
-    It is not recommended to use `cloud-bukkit`. Instead, we recommend using [cloud-paper](paper.md) which works on both
-    Spigot & Paper servers, and offers access to modern features such as Brigadier and asynchronous suggestions.
-
-## Installation
-
-Cloud for Bukkit is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
-
-<!-- prettier-ignore -->
-=== "Maven"
-
-    ```xml
-    <dependencies>
-        <dependency>
-            <groupId>cloud.commandframework</groupId>
-            <artifactId>cloud-bukkit</artifactId>
-            <version>2.0.0-SNAPSHOT</version>
-        </dependency>
-    </dependencies>
-    ```
-
-=== "Gradle (Kotlin)"
-
-    ```kotlin
-    implementation("cloud.commandframework:cloud-bukkit:2.0.0-SNAPSHOT")
-    ```
-
-=== "Gradle (Groovy)"
-
-    ```groovy
-    implementation 'cloud.commandframework:cloud-bukkit:2.0.0-SNAPSHOT'
-    ```
-
-## Usage
-
-`cloud-bukkit` has a command manager implementation called `BukkitCommandManager`, which you construct like:
-
-```java
-BukkitCommandManager<YourSenderType> commandManager = new BukkitCommandManager<>(
-  yourPlugin /* 1 */,
-  executionCoordinator /* 2 */,
-  senderMapper /* 3 */
-);
-```
-
-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.
-2. Information about execution coordinators can be found
-   [here](../core/index.md#execution-coordinators).
-3. The sender mapper is a two-way mapping between Bukkit's
-   [CommandSender](https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandSender.html) and your custom sender type.
-   If you use `CommandSender` as the sender type, then you may use `SenderMapper.identity()`.
+The `cloud-bukkit` module is home to parsers and other classes that make up the base of Cloud for Bukkit-based platforms.
+`cloud-bukkit` is not intended to be consumed as a direct dependency, instead it should be consumed as
+a transitive dependency of [`cloud-paper`](paper.md).
 
 ## Parsers
 

diff --git a/docs/minecraft/index.md b/docs/minecraft/index.md
@@ -1,4 +1,4 @@
-# cloud-minecraft
+# [cloud-minecraft](https://github.com/Incendo/cloud-minecraft)
 
 ## Modules
 
@@ -10,9 +10,13 @@
 - [Paper](./paper.md): Paper/Spigot integration
 - [Velocity](./velocity.md): Velocity integration
 - [BungeeCord](./bungee.md): BungeeCord integration
-- [NeoForge](./neoforge.md): NeoForge integration
-- [Fabric](./fabric.md): Fabric integration
 - [Sponge](./sponge.md): Sponge integration
 - [Cloudburst](./cloudburst.md): CloudBurst integration
 
 </div>
+
+See also:
+
+<div class="grid cards" markdown>
+- [`cloud-minecraft-modded`](modded/index.md) for Fabric and NeoForge integrations
+</div>
diff --git a/docs/minecraft/minecraft-extras.md b/docs/minecraft/minecraft-extras.md
@@ -19,7 +19,7 @@
 
 ## Installation
 
-Cloud Minecraft Extras is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud Minecraft Extras is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-minecraft-extras).
 
 <!-- prettier-ignore -->
 === "Maven"
@@ -101,6 +101,7 @@ or you may override the defaults by using a builder:
       .commandManager(commandManager)
       .audienceProvider(AudienceProvider.nativeProvider())
       .commandPrefix("/helpcommand")
+      .withColors(MinecraftHelp.helpColors(/* colors... */))
       /* other settings... */
       .build();
     ```
@@ -112,6 +113,7 @@ or you may override the defaults by using a builder:
       .commandManager(commandManager)
       .audienceProvider(yourAudienceProvider)
       .commandPrefix("/helpcommand")
+      .withColors(MinecraftHelp.helpColors(/* colors... */))
       /* other settings... */
       .build();
     ```

diff --git a/docs/minecraft/fabric.md → docs/minecraft/modded/fabric.md b/docs/minecraft/fabric.md → docs/minecraft/modded/fabric.md
diff --git a/docs/minecraft/modded/index.md b/docs/minecraft/modded/index.md
@@ -0,0 +1,19 @@
+# [cloud-minecraft-modded](https://github.com/Incendo/cloud-minecraft-modded)
+
+## Modules
+
+<div class="grid cards" markdown>
+
+- [Fabric](./fabric.md): Fabric integration
+- [NeoForge](./neoforge.md): NeoForge integration
+- [Common](#common): Code shared between Fabric and NeoForge
+
+</div>
+
+## Compatibility
+
+| Minecraft version range | `cloud-minecraft-modded` version |
+| ----------------------- | -------------------------------- |
+| 1.19.4+                 | 2.0.0-SNAPSHOT                   |
+
+## Common
diff --git a/docs/minecraft/neoforge.md → docs/minecraft/modded/neoforge.md b/docs/minecraft/neoforge.md → docs/minecraft/modded/neoforge.md
diff --git a/docs/minecraft/paper.md b/docs/minecraft/paper.md
@@ -1,16 +1,15 @@
 # cloud-paper
 
 <!-- prettier-ignore -->
-!!! note
-    It is recommended that you read the [cloud-bukkit](bukkit.md) documentation as well, as the different topics
-    covered there apply to `cloud-paper` as well.
-
-`cloud-paper` is an extension of [cloud-bukkit](bukkit.md) with additions for Paper servers. You may use
-`cloud-paper` on non-Paper servers, in which case the Paper-specific features will be disabled.
+`cloud-paper` is an extension of `cloud-bukkit` with additional support for
+[Paper](https://papermc.io/software/paper)-based platforms. `cloud-paper` maintains support for all platforms supported
+by `cloud-bukkit`, and therefore is the recommended dependency to use Cloud on any Bukkit-based platform.
+The following documentation is written with the assumption that you have already read and understand the
+[`cloud-bukkit` documentation](bukkit.md).
 
 ## Installation
 
-Cloud for Paper is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+Cloud for Paper is available through [Maven Central](https://central.sonatype.com/artifact/cloud.commandframework/cloud-paper).
 
 <!-- prettier-ignore -->
 === "Maven"
@@ -39,30 +38,42 @@ Cloud for Paper is available through [Maven Central](https://search.maven.org/se
 
 ## Usage
 
-`cloud-paper` has a command manager implementation called `PaperCommandManager`, which you construct like:
+`cloud-paper` has a command manager implementation called `PaperCommandManager` that can be created in two ways.
+
+With a custom sender type:
 
 ```java
 PaperCommandManager<YourSenderType> commandManager = new PaperCommandManager<>(
-  yourPlugin /* 1 */,
-  executionCoordinator /* 2 */,
+  yourPlugin, /* 1 */
+  executionCoordinator, /* 2 */
   senderMapper /* 3 */
 );
 ```
 
+Or, using Bukkit's [`CommandSender`](https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandSender.html):
+
+```java
+PaperCommandManager<CommandSender> commandManager = PaperCommandManager.createNative(
+  yourPlugin, /* 1 */
+  executionCoordinator /* 2 */
+);
+```
+
 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.
-2. Information about execution coordinators can be found
-   [here](../core/index.md#execution-coordinators).
+2. Information about execution coordinators in general can be found
+   [here](../core/index.md#execution-coordinators). See [below](#execution-coordinators) for info specific to
+   Bukkit-based platforms.
 3. The sender mapper is a two-way mapping between Bukkit's
-   [CommandSender](https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandSender.html) and your custom sender type.
-   If you use `CommandSender` as the sender type, then you may use `SenderMapper.identity()`.
+   [`CommandSender`](https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandSender.html) and your custom sender type.
+   Using `SenderMapper.identity()` is equivalent to the `createNative` static factory method.
 
 ## Brigadier
 
 Paper exposes Brigadier, which means that you may use the features from [cloud-brigadier](brigadier.md) on Paper
 servers.
 
-You may enable Brigadier mappings using `PaperCommandManager.registerBrigadier()`. You should make use of the
+You may enable Brigadier mappings using `PaperCommandManager#registerBrigadier()`. You should make use of the
 capability system to make sure that Brigadier is available on the server your plugin is running on:
 
 ```java
@@ -71,16 +82,17 @@ if (commandManager.hasCapability(CloudBukkitCapabilities.NATIVE_BRIGADIER)) {
 }
 ```
 
-## Asynchronous Completions
+## Asynchronous completions
 
 <!-- prettier-ignore -->
 !!! note
-    You should not use asynchronous completions together with Brigadier. Brigadier suggestions are already non-blocking.
+    You should not use asynchronous completions together with Brigadier. Brigadier suggestions are already non-blocking,
+    and the asynchronous completion API reduces the fidelity of suggestions compared to Brigadier alone.
 
 Paper allows for non-blocking suggestions. You are highly recommended to make use of this, as Cloud will invoke
 the argument parsers during suggestion generation which ideally should not take place on the main server thread.
 
-You may enable asynchronous completions using `PaperCommandManager.registerAsynchronousCompletions()`.
+You may enable asynchronous completions using `PaperCommandManager#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
@@ -89,6 +101,27 @@ if (commandManager.hasCapability(CloudBukkitCapabilities.ASYNCHRONOUS_COMPLETION
 }
 ```
 
+## Execution coordinators
+
+Due to Bukkit blocking the main thread for suggestion requests, it's potentially unsafe to use anything other than
+`ExecutionCoordinator.nonSchedulingExecutor()` for
+`ExecutionCoordinator.Builder#suggestionsExecutor(Executor)`. Once the coordinator, a suggestion provider, parser,
+or similar routes suggestion logic off of the calling \(main) thread, it won't be possible to schedule further logic
+back to the main thread without a deadlock. When Brigadier support is active, this issue is avoided, as it allows
+for non-blocking suggestions. Paper's [asynchronous completions](#asynchronous-completions) API can also be used to
+avoid this issue, however when Brigadier is available it should be preferred (for reasons mentioned above).
+
+Example code to avoid this problem:
+
+```java
+if (commandManager.hasCapability(CloudBukkitCapabilities.NATIVE_BRIGADIER)) {
+  commandManager.registerBrigadier();
+} else if (commandManager.hasCapability(CloudBukkitCapabilities.ASYNCHRONOUS_COMPLETION)) {
+  commandManager.registerAsynchronousCompletions();
+}
+// else: we can't avoid the problem, very old Paper or Spigot
+```
+
 ## Parsers
 
 `cloud-paper` has access to all the parsers from [cloud-bukkit](bukkit.md#parsers).
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -35,8 +35,10 @@ nav:
       - cloud-bungee: minecraft/bungee.md
       - cloud-cloudburst: minecraft/cloudburst.md
       - cloud-sponge: minecraft/sponge.md
-      - cloud-fabric: minecraft/fabric.md
-      - cloud-neoforge: minecraft/neoforge.md
+  - cloud-minecraft-modded:
+      - cloud-minecraft-modded: minecraft/modded/index.md
+      - cloud-fabric: minecraft/modded/fabric.md
+      - cloud-neoforge: minecraft/modded/neoforge.md
   - cloud-spring:
       - cloud-spring: spring/index.md
   - cloud-processors: