diff --git a/.gitignore b/.gitignore index 2a0539e..1b44fdb 100644 --- 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 \ No newline at end of file +# 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 index f179fb9..57c9eed 100644 --- 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). === "Maven" diff --git a/docs/core/index.md b/docs/core/index.md index 743a470..eaf4819 100644 --- 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). === "Maven" diff --git a/docs/discord/discord4j.md b/docs/discord/discord4j.md index 86b5039..26c0923 100644 --- 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). === "Maven" diff --git a/docs/discord/jda5.md b/docs/discord/jda5.md index 279422b..1c05cf8 100644 --- 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). === "Maven" diff --git a/docs/discord/kord.md b/docs/discord/kord.md index 3e0a71f..5124b07 100644 --- 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). === "Maven" diff --git a/docs/kotlin/annotations.md b/docs/kotlin/annotations.md index 7fc4ea7..1998e57 100644 --- 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). === "Gradle (Kotlin)" diff --git a/docs/kotlin/coroutines.md b/docs/kotlin/coroutines.md index 62204dd..c407807 100644 --- 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). === "Gradle (Kotlin)" diff --git a/docs/kotlin/extensions.md b/docs/kotlin/extensions.md index e8d4f81..e0fa3be 100644 --- 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). === "Gradle (Kotlin)" diff --git a/docs/minecraft/bukkit.md b/docs/minecraft/bukkit.md index 04b4d95..aed146b 100644 --- a/docs/minecraft/bukkit.md +++ b/docs/minecraft/bukkit.md @@ -1,58 +1,8 @@ # cloud-bukkit - -!!! 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). - - -=== "Maven" - - ```xml - - - cloud.commandframework - cloud-bukkit - 2.0.0-SNAPSHOT - - - ``` - -=== "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 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 index 6c6f88e..b33bedc 100644 --- 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 + +See also: + +
+- [`cloud-minecraft-modded`](modded/index.md) for Fabric and NeoForge integrations +
diff --git a/docs/minecraft/minecraft-extras.md b/docs/minecraft/minecraft-extras.md index 06a7180..226c957 100644 --- 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). === "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 b/docs/minecraft/modded/fabric.md similarity index 100% rename from docs/minecraft/fabric.md rename to docs/minecraft/modded/fabric.md diff --git a/docs/minecraft/modded/index.md b/docs/minecraft/modded/index.md new file mode 100644 index 0000000..8cd3451 --- /dev/null +++ b/docs/minecraft/modded/index.md @@ -0,0 +1,19 @@ +# [cloud-minecraft-modded](https://github.com/Incendo/cloud-minecraft-modded) + +## Modules + +
+ +- [Fabric](./fabric.md): Fabric integration +- [NeoForge](./neoforge.md): NeoForge integration +- [Common](#common): Code shared between Fabric and NeoForge + +
+ +## Compatibility + +| Minecraft version range | `cloud-minecraft-modded` version | +| ----------------------- | -------------------------------- | +| 1.19.4+ | 2.0.0-SNAPSHOT | + +## Common diff --git a/docs/minecraft/neoforge.md b/docs/minecraft/modded/neoforge.md similarity index 100% rename from docs/minecraft/neoforge.md rename to docs/minecraft/modded/neoforge.md diff --git a/docs/minecraft/paper.md b/docs/minecraft/paper.md index c6ee887..4169c3f 100644 --- a/docs/minecraft/paper.md +++ b/docs/minecraft/paper.md @@ -1,16 +1,15 @@ # cloud-paper -!!! 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). === "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 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 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 !!! 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 index edc9bf3..ff24e7b 100644 --- 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: