From 5e2b8ca5c66da7a6c623124da1c1245c76531eb8 Mon Sep 17 00:00:00 2001 From: kilian Date: Thu, 21 Dec 2023 17:55:06 +0100 Subject: [PATCH] Update the Brigadier guide (#60) * chore: Update the brigadier command docs and example * fix: Rename brigardier to brigadier * fix: Inline danger block --- .../commands/{brigardier.md => brigadier.md} | 60 +++++++++++++------ guide/docs/commands/brigadier_example.md | 19 ++++++ guide/docs/commands/brigardier_example.md | 19 ------ guide/mkdocs.yml | 4 +- 4 files changed, 63 insertions(+), 39 deletions(-) rename guide/docs/commands/{brigardier.md => brigadier.md} (50%) create mode 100644 guide/docs/commands/brigadier_example.md delete mode 100644 guide/docs/commands/brigardier_example.md diff --git a/guide/docs/commands/brigardier.md b/guide/docs/commands/brigadier.md similarity index 50% rename from guide/docs/commands/brigardier.md rename to guide/docs/commands/brigadier.md index dfc0d193..10dfe1e5 100644 --- a/guide/docs/commands/brigardier.md +++ b/guide/docs/commands/brigadier.md @@ -1,8 +1,8 @@ -# Brigardier support +# Brigadier support -???+ warning "Brigardier dependency for spigot-api users" - (You do only have to do the following if you are using the `spigot-api` instead of the `spigot` dependency!)
- Whilst Spigot itself depends on [Brigardier](https://github.com/Mojang/brigadier#gradle) the Spigot API doesn't so in order for this feature to work you need to add Brigardier as a `compileOnly` dependency. More information on that can be found here: [https://github.com/Mojang/brigadier#gradle](https://github.com/Mojang/brigadier#gradle) +???+ warning "Brigadier dependency for spigot-api users" + (You only have to do the following if you are using the `spigot-api` instead of the `spigot` dependency!)
+ Whilst Spigot itself depends on [Brigadier](https://github.com/Mojang/brigadier#gradle) the Spigot API doesn't so in order for this feature to work you need to add Brigadier as a `compileOnly` dependency. More information on that can be found here: [https://github.com/Mojang/brigadier#gradle](https://github.com/Mojang/brigadier#gradle) ## Create a command @@ -12,6 +12,9 @@ command("mycommand") { } ``` +???+ danger + Do not add the command in your plugin.yml, this will interfere with Brigadier + ## Register the command The command will be automatically registered by default, **if you are initializing it before the end of the `startup` call @@ -27,13 +30,32 @@ which the `command(name)` function returns). You can infinitely nest all these functions, resulting in complex command structures.
### Execution handler +You can define your execution logic using the `executes` (with a status code) or `runs` function. -You provide your execution logic using the `executes` (with status code) or `simpleExecutes` (status code is always 1) -function. +#### Runs + +Setting the status code explicitly: +```kotlin +runs { context -> + context.bukkitSender.sendMessage("hey gamer ;)") + return@runs 1 +} +``` + +Alternatively you could use it as following: +```kotlin +runs { + this.sender.bukkitSender.sendMessage("hey gamer ;)") +} +``` +Automatically returning the status code 1. + +#### Executes ```kotlin -simpleExecutes { context -> - context.source.bukkitSender.sendMessage("hey gamer ;)") +executes { context -> + context.bukkitSender.sendMessage("hey gamer ;)") + return@executes 1 } ``` @@ -43,12 +65,14 @@ simpleExecutes { context -> #### The command context -You can use the command context to get the command source. You can use the source for: +You can use the command context in `executes` to get the command source. You can use the source for: - `source.bukkitSender` to get the `CommandSender` - `source.player` ensure that a player executed the command and get that `Player` - `source.bukkitWorld` to get the world of the executor +If you are using `runs`, you can access these by using `sender` instead of `source`. + ### Literals (subcommands) ```kotlin @@ -70,8 +94,8 @@ execution handler. #### Argument type -The second paramter of the argument function is the argument type. There are a lot of pre defined argument types by -brigardier. +The second parameter of the argument function is the argument type. There are a lot of pre-defined argument types by +brigadier. The argument types for all primitives can be accessed in the following pattern: `NameArgumentType.name()` (where name is the name of the primitive) @@ -88,22 +112,22 @@ The value of the argument can be retrieved from the command context. ```kotlin argument("argumentname", StringArgumentType.string()) { - simpleExecutes { - val argValue = it.getArgument("argumentname") + runs { + val argValue = this.getArgument("argumentname") // or using reified you can omit the type sometimes - mapWhereTheKeysAreStrings[it.getArgument("argumentname")] + mapWhereTheKeysAreStrings[this.getArgument("argumentname")] } } ``` ### Suggestions -You can provide argument suggestions using the `simpleSuggests` function. It is **not** recommended using the default +You can provide argument suggestions using the `suggestList` function. It is **not** recommended using the default `suggests` function. ```kotlin -simpleSuggests { Material.values().toList() } +suggestList { Material.values().toList() } ``` -It is okay to do heavy operations inside this function. Suggestions are asynchronous. The body of the `simpleSuggests` -function is suspending, meaning you can use kotlinx.coroutines in it. +If you want to do heavy operations inside the suggest functions, you should use `suggestListSuspending` +The body of the `suggestListSuspending` function is suspending, meaning you can use kotlinx.coroutines in it. diff --git a/guide/docs/commands/brigadier_example.md b/guide/docs/commands/brigadier_example.md new file mode 100644 index 00000000..7d0955b1 --- /dev/null +++ b/guide/docs/commands/brigadier_example.md @@ -0,0 +1,19 @@ +The following command illustrates how to use commands, subcommands, arguments and the command context. + +```kotlin +command("gaming") { + literal("set") { + argument("state", BoolArgumentType.bool()) { + suggestList { listOf(true, false) } + runs { + if (this.getArgument("state")) + this.player.sendMessage("yoo gaming has been activated") + else { + this.player.kill() + this.player.sendText("gaming disabled"){ color = KColors.INDIANRED } + } + } + } + } +} +``` diff --git a/guide/docs/commands/brigardier_example.md b/guide/docs/commands/brigardier_example.md deleted file mode 100644 index f0af1a8c..00000000 --- a/guide/docs/commands/brigardier_example.md +++ /dev/null @@ -1,19 +0,0 @@ -The following command illustrates how to use commands, subcommands, arguments and the command context. - -```kotlin -command("gaming") { - literal("set") { - argument("state", BoolArgumentType.bool()) { - simpleSuggests { listOf(true, false) } - simpleExecutes { - if (it.getArgument("state")) - it.source.bukkitSender.sendMessage("yoo gaming has been activated") - else { - it.source.player.kill() - it.source.player.sendText("gaming disabled") { color = KColors.INDIANRED } - } - } - } - } -} -``` diff --git a/guide/mkdocs.yml b/guide/mkdocs.yml index 6ef0eb83..2139d92a 100644 --- a/guide/mkdocs.yml +++ b/guide/mkdocs.yml @@ -44,8 +44,8 @@ nav: - Gui: - Compounds: gui/compounds.md - Commands: - - Brigardier: commands/brigardier.md - - Brigardier example: commands/brigardier_example.md + - Brigadier: commands/brigadier.md + - Brigadier example: commands/brigadier_example.md - Migration: - "1.17 to 1.18": migration/1_17_to_1_18.md - "1.16 to 1.17": migration/1_16_to_1_17.md