Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Jan 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@
.idea/**/usage.statistics.xml
.idea/**/dictionaries
.idea/**/shelf
.idea/**

# AWS User-specific
.idea/**/aws.xml
Expand Down Expand Up @@ -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
2 changes: 1 addition & 1 deletion docs/annotations/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion docs/core/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion docs/discord/discord4j.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion docs/discord/jda5.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion docs/discord/kord.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion docs/kotlin/annotations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
Expand Down
2 changes: 1 addition & 1 deletion docs/kotlin/coroutines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
Expand Down
2 changes: 1 addition & 1 deletion docs/kotlin/extensions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)"
Expand Down
56 changes: 3 additions & 53 deletions docs/minecraft/bukkit.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
10 changes: 7 additions & 3 deletions docs/minecraft/index.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# cloud-minecraft
# [cloud-minecraft](https://github.com/Incendo/cloud-minecraft)

## Modules

Expand All @@ -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>
4 changes: 3 additions & 1 deletion docs/minecraft/minecraft-extras.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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();
```
Expand All @@ -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();
```
Expand Down
File renamed without changes.
19 changes: 19 additions & 0 deletions docs/minecraft/modded/index.md
Original file line number Diff line number Diff line change
@@ -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
File renamed without changes.
69 changes: 51 additions & 18 deletions docs/minecraft/paper.md
Original file line number Diff line number Diff line change
@@ -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"
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Citymonstret marked this conversation as resolved.
Show resolved Hide resolved
`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).
6 changes: 4 additions & 2 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading