From bdd65333992843f710792479228088a93f6b7fff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20S=C3=B6derberg?= Date: Tue, 23 Jan 2024 18:55:18 +0100 Subject: [PATCH] feat(minecraft): more Bukkit & Paper docs --- docs/minecraft/bukkit.md | 89 ++++++++++++++++++++++++++++++++-------- docs/minecraft/paper.md | 25 +++++++++++ 2 files changed, 96 insertions(+), 18 deletions(-) diff --git a/docs/minecraft/bukkit.md b/docs/minecraft/bukkit.md index f8d3038..04b4d95 100644 --- a/docs/minecraft/bukkit.md +++ b/docs/minecraft/bukkit.md @@ -34,23 +34,76 @@ Cloud for Bukkit is available through [Maven Central](https://search.maven.org/s 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()`. + ## Parsers -| Parser | Type (\* = cloud type) | Brigadier Type | -| ---------------------------- | ---------------------------------------------------------------------------------------- | ------------------- | -| UUIDParser | [UUID](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/UUID.html) | `uuid` | -| NamespacedKeyParser | [NamespacedKey](https://jd.papermc.io/paper/1.20/org/bukkit/NamespacedKey.html) | `resource_location` | -| EnchantmentParser | [Enchantment](https://jd.papermc.io/paper/1.20/org/bukkit/enchantments/Enchantment.html) | `enchantment` | -| ItemStackParser | ProtoItemStack\* | `item_stack` | -| ItemStackPredicateParser | ItemStackPredicate\* | `item_predicate` | -| BlockPredicateParser | BlockPredicate\* | `block_predicate` | -| SingleEntitySelectorParser | SingleEntitySelector\* | `entity` | -| SinglePlayerSelectorParser | SinglePlayerSelector\* | `entity` | -| MultipleEntitySelectorParser | MultipleEntitySelector\* | `entity` | -| MultiplePlayerSelectorParser | MultiplePlayerSelector\* | `entity` | -| LocationParser | [Location](https://jd.papermc.io/paper/1.20/org/bukkit/Location.html) | `vec3` | -| Location2DParser | Location2D\* | `vec2` | -| MaterialParser | [Material](https://jd.papermc.io/paper/1.20/org/bukkit/Material.html) | | -| OfflinePlayerParser | [OfflinePlayer](https://jd.papermc.io/paper/1.20/org/bukkit/OfflinePlayer.html) | | -| PlayerPayer | [Player](https://jd.papermc.io/paper/1.20/org/bukkit/entity/Player.html) | | -| WorldParser | [World](https://jd.papermc.io/paper/1.20/org/bukkit/World.html) | | +| Parser | Type (\* = cloud type) | Brigadier Type | Note | +| ---------------------------- | ---------------------------------------------------------------------------------------- | ------------------- | | +| UUIDParser | [UUID](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/UUID.html) | `uuid` | [link](#namespacedkeyparser) | +| NamespacedKeyParser | [NamespacedKey](https://jd.papermc.io/paper/1.20/org/bukkit/NamespacedKey.html) | `resource_location` | | +| EnchantmentParser | [Enchantment](https://jd.papermc.io/paper/1.20/org/bukkit/enchantments/Enchantment.html) | `enchantment` | | +| ItemStackParser | ProtoItemStack\* | `item_stack` | | +| ItemStackPredicateParser | ItemStackPredicate\* | `item_predicate` | | +| BlockPredicateParser | BlockPredicate\* | `block_predicate` | | +| SingleEntitySelectorParser | SingleEntitySelector\* | `entity` | [link](#selectors) | +| SinglePlayerSelectorParser | SinglePlayerSelector\* | `entity` | [link](#selectors) | +| MultipleEntitySelectorParser | MultipleEntitySelector\* | `entity` | [link](#selectors) | +| MultiplePlayerSelectorParser | MultiplePlayerSelector\* | `entity` | [link](#selectors) | +| LocationParser | [Location](https://jd.papermc.io/paper/1.20/org/bukkit/Location.html) | `vec3` | | +| Location2DParser | Location2D\* | `vec2` | | +| MaterialParser | [Material](https://jd.papermc.io/paper/1.20/org/bukkit/Material.html) | | | +| OfflinePlayerParser | [OfflinePlayer](https://jd.papermc.io/paper/1.20/org/bukkit/OfflinePlayer.html) | | | +| PlayerPayer | [Player](https://jd.papermc.io/paper/1.20/org/bukkit/entity/Player.html) | | | +| WorldParser | [World](https://jd.papermc.io/paper/1.20/org/bukkit/World.html) | | | + +### NamespacedKeyParser + +The `NamespacedKeyParser` parses namespaced key in the form `namespace:key`. + +#### Annotations + +###### `@DefaultNamespace` + +Use `@DefaultNamespace("namespace")` on a component to set the namespace which will be used in the case that no +namespace is supplied by the command sender. + +###### `@RequireExplicitNamespace` + +Use `@RequireExplicitNamespace` to fail parsing if the command sender does not supply a namespace. + +### Selectors + +#### Annotations + +##### `@AllowEmptySelection` + +Use `@AllowEmptySelection` to allow the command sender to execute a command with a selector which selects zero entities. + +## Descriptions + +Cloud will register all root literals to the Bukkit [CommandMap](https://jd.papermc.io/paper/1.20/org/bukkit/command/CommandMap.html) +which means that they will show up in the Bukkit help menu. +Cloud will try to determine the description for the Bukkit help menu by: + +1. Use the `BukkitCommandMeta.BUKKIT_DESCRIPTION` [meta](../core/index.md#command-meta) value of the command, if it exists. +2. Using the [CommandDescription](../core/index.md#command-descriptions), if a command is attached directly to the root literal. +3. Use the root literal [Description](../core/index.md#component-descriptions), if it's non-empty. diff --git a/docs/minecraft/paper.md b/docs/minecraft/paper.md index 622f426..c6ee887 100644 --- a/docs/minecraft/paper.md +++ b/docs/minecraft/paper.md @@ -1,5 +1,10 @@ # 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. @@ -32,6 +37,26 @@ Cloud for Paper is available through [Maven Central](https://search.maven.org/se implementation 'cloud.commandframework:cloud-paper:2.0.0-SNAPSHOT' ``` +## Usage + +`cloud-paper` has a command manager implementation called `PaperCommandManager`, which you construct like: + +```java +PaperCommandManager commandManager = new PaperCommandManager<>( + 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()`. + ## Brigadier Paper exposes Brigadier, which means that you may use the features from [cloud-brigadier](brigadier.md) on Paper