5e2b8ca5c6
* chore: Update the brigadier command docs and example * fix: Rename brigardier to brigadier * fix: Inline danger block
134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
# Brigadier support
|
|
|
|
???+ 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!) <br>
|
|
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
|
|
|
|
```kotlin
|
|
command("mycommand") {
|
|
// the command body
|
|
}
|
|
```
|
|
|
|
???+ 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
|
|
to your plugin.**
|
|
|
|
Otherwise, you can register it manually using the `command.register()` function (where command is the command instance
|
|
which the `command(name)` function returns).
|
|
|
|
## Command features
|
|
|
|
???+ danger "Where to call these? How to structure these?"
|
|
All the following features can be used inside the command body. <br>
|
|
You can infinitely nest all these functions, resulting in complex command structures. <br>
|
|
|
|
### Execution handler
|
|
You can define your execution logic using the `executes` (with a status code) or `runs` 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
|
|
executes { context ->
|
|
context.bukkitSender.sendMessage("hey gamer ;)")
|
|
return@executes 1
|
|
}
|
|
```
|
|
|
|
???+ info
|
|
The execution and suggestion providers always do only apply to the location in the tree where they are
|
|
defined.
|
|
|
|
#### The command context
|
|
|
|
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
|
|
literal("mysubcommand") {
|
|
// the command body for this part of the command tree
|
|
}
|
|
```
|
|
|
|
### Arguments
|
|
|
|
```kotlin
|
|
argument("argumentname", StringArgumentType.string()) {
|
|
// the command body (inside this body, the argument exists in the context)
|
|
}
|
|
```
|
|
|
|
The argument name will be displayed to the player. Also, it can be used to retrieve the value of the argument the
|
|
execution handler.
|
|
|
|
#### Argument type
|
|
|
|
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)
|
|
|
|
```kotlin
|
|
// examples:
|
|
StringArgumentType.string()
|
|
BoolArgumentType.bool()
|
|
IntegerArgumentType.integer()
|
|
```
|
|
|
|
#### Retrieve the value of an argument
|
|
|
|
The value of the argument can be retrieved from the command context.
|
|
|
|
```kotlin
|
|
argument("argumentname", StringArgumentType.string()) {
|
|
runs {
|
|
val argValue = this.getArgument<String>("argumentname")
|
|
// or using reified you can omit the type sometimes
|
|
mapWhereTheKeysAreStrings[this.getArgument("argumentname")]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Suggestions
|
|
|
|
You can provide argument suggestions using the `suggestList` function. It is **not** recommended using the default
|
|
`suggests` function.
|
|
|
|
```kotlin
|
|
suggestList { Material.values().toList() }
|
|
```
|
|
|
|
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.
|