You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en/annotations/annotations.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -52,17 +52,17 @@ To use annotations on methods, **methods must be static**.
52
52
53
53
### `@Default`
54
54
55
-
The `@Default` annotation indicates that the method is _not_ a subcommand. This acts in a similar way to regular Bukkit commands. Commands with the `@Default` annotation can be used to run the main code when the command named with the `@Command` annotation is stated, such as the following:
55
+
The `@Default` annotation indicates that the method is _not_ a subcommand. This acts similarly to regular Bukkit commands. Commands with the `@Default` annotation can be used to run the main code when the command named with the `@Command` annotation is stated, such as the following:
The `@Subcommand` simply tells the CommandAPI that the declared method is a subcommand. This acts in a similar way to the regular CommandAPI's `.withSubcommand()` method. The subcommand annotation can take in a single string which is the name of the subcommand:
65
+
The `@Subcommand` simply tells the CommandAPI that the declared method is a subcommand. This acts similarly to the regular CommandAPI's `.withSubcommand()` method. The subcommand annotation can take in a single string which is the name of the subcommand:
@@ -82,7 +82,7 @@ The `@NeedsOp` annotation can also be used on methods to indicate that the user
82
82
83
83
## Annotations that go on parameters
84
84
85
-
The annotations for arguments are really simple, there's just two things you need to know:
85
+
The annotations for arguments are really simple, there are just two things you need to know:
86
86
87
87
- To use an annotation argument, just add the letter `A` (for 'annotation') at the beginning of it! For example:
88
88
@@ -119,6 +119,6 @@ For the `@ALiteralArgument` annotation, the parameter is the literal to be used
119
119
120
120
#### Other arguments
121
121
122
-
The `LocationArgument`, `Location2DArgument`, `EntitySelectorArgument` and `ScoreHolderArgument` can all take an extra parameter in their constructors. As a result, the annotation-equivalent of these arguments also allow you to provide the parameter in the annotation:
122
+
The `LocationArgument`, `Location2DArgument`, `EntitySelectorArgument` and `ScoreHolderArgument` can all take an extra parameter in their constructors. As a result, the annotation-equivalent of these arguments also allows you to provide the parameter in the annotation:
Copy file name to clipboardExpand all lines: docs/en/annotations/intro.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,14 +6,14 @@ authors:
6
6
7
7
# Annotation-based commands
8
8
9
-
The CommandAPI also includes a very small lightweight annotation-based command framework. This works very differently compared to previous commands shown in this documentation and **it is less feature-rich than registering commands using the other methods.**
9
+
The CommandAPI also includes a tiny lightweight annotation-based command framework. This works very differently compared to previous commands shown in this documentation, and **it is less feature-rich than registering commands using the other methods.**
10
10
11
11
In short, the CommandAPI's annotation-based system:
12
12
13
-
- Has no runtime overhead compared to using the regular command registration system (unlike other annotation-based frameworks such as [ACF](https://github.com/aikar/commands)).
13
+
-It Has no runtime overhead compared to using the regular command registration system (unlike other annotation-based frameworks such as [ACF](https://github.com/aikar/commands)).
14
14
- Reduces code bloat (to an extent).
15
15
- Improves readability since commands are declared declaratively instead of imperatively.
16
-
- Is not as powerful as the regular command registration system.
16
+
-It Is not as powerful as the regular command registration system.
17
17
18
18
:::info
19
19
@@ -49,7 +49,7 @@ Seems fairly straightforward, given everything else covered in this documentatio
49
49
50
50
### Warp command (with annotations)
51
51
52
-
I think it's best to show the example and the explain it afterwards:
52
+
I think it's best to show the example and explain it afterward:
Here, declare the main command implementation using the `@Default` annotation. The `@Default` annotation informs the CommandAPI that the method it is attached to does not have any subcommands. This is effectively the same as registering a regular command without using `.withSubcommand()`.
71
+
Here, declare the main command implementation using the `@Default` annotation. The `@Default` annotation informs the CommandAPI that the method it is attached to doesn’t have any subcommands. This is effectively the same as registering a regular command without using `.withSubcommand()`.
72
72
73
-
Here, we simply write what happens when no arguments are run (i.e. the user just runs `/warp` on its own). As such, we don't include any parameters to our method.
73
+
Here, we simply write what happens when no arguments are run (i.e., the user just runs `/warp` on its own). As such, we don't include any parameters to our method.
We also have a second `@Default` annotated method, which handles our `/warp <warp>` command. Because this isn't a subcommand (the warp to teleport to is not a subcommand, it's an argument), we still using the `@Default` annotation. In this method, we include an argument with this command by using the `@AStringArgument` annotation. This argument uses the `StringArgument` class, and the name of this argument is "warpName", which is extracted from the name of the variable. Simply put, **the Annotation for an argument is A** followed by the name of the argument. This is synonymous with using the following:
79
+
We also have a second `@Default` annotated method, which handles our `/warp <warp>` command. Because this isn't a subcommand (the warp to teleport to is not a subcommand, it's an argument), we're still using the `@Default` annotation. In this method, we include an argument with this command by using the `@AStringArgument` annotation. This argument uses the `StringArgument` class, and the name of this argument is "warpName", which is extracted from the name of the variable. Simply put, **the Annotation for an argument is A** followed by the name of the argument. This is synonymous with using the following:
80
80
81
81
```java
82
82
newStringArgument("warp")
83
83
```
84
84
85
-
It's also very important to note the parameters for this method. The first parameter is a `Player` object, which represents our command sender. The CommandAPI's annotation system uses the fact that the command sender is a `Player` object and automatically ensures that anyone using the command must be a `Player`. In other words, non-players (such as the console or command blocks), would be unable to execute this command.
85
+
It's also crucial to note the parameters for this method. The first parameter is a `Player` object, which represents our command sender. The CommandAPI's annotation system uses the fact that the command sender is a `Player` object and automatically ensures that anyone using the command must be a `Player`. In other words, non-players (such as the console or command blocks), would be unable to execute this command.
86
86
87
87
The second argument is a `String` object, which represents the result of our argument "warp". The CommandAPI's annotation system can also infer the return type of the argument that is provided to it (in this case, a `StringArgument` will produce a `String`) and will automatically cast and provide the result to that parameter.
Lastly, we declare a subcommand to allow us to run `/warp create <name>`. To do this, we simply use the `@Subcommand` annotation. In this example, we also apply a permission node that is required to run the command by using the `@Permission` annotation. The rest is fairly straight forward - we declare an argument, in this case it's another `StringArgument` , so we use `@AStringArgument` and then declare everything else in a similar fashion to the default command executor.
93
+
Lastly, we declare a subcommand to allow us to run `/warp create <name>`. To do this, we simply use the `@Subcommand` annotation. In this example, we also apply a permission node required to run the command by using the `@Permission` annotation. The rest is fairly straight forward – we declare an argument, in this case it's another `StringArgument` , so we use `@AStringArgument` and then declare everything else in a similar fashion to the default command executor.
94
94
95
95
#### Registering the command
96
96
97
-
Registering the command is fairly simple and is a oneliner:
97
+
Registering the command is fairly simple and is a one-liner:
Copy file name to clipboardExpand all lines: docs/en/contribution/project-structure.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,22 +6,22 @@ authors:
6
6
7
7
# Project Structure
8
8
9
-
The CommandAPI is a relatively large project (especially from the standpoint of one guy, because the CommandAPI was written by just one guy in their spare time!) and trying to figure out what everything does is a nightmare without some guidance. I've always felt that other community project structures aren't well documented and contributing to them can be daunting. Here's the CommandAPI's project structure for you!
9
+
The CommandAPI is a relatively large project (especially from the standpoint of one guy, because the CommandAPI was written by just one guy in their spare time!) and trying to figure out what everything does is a nightmare without any guidance. I've always felt that other community project structures aren't well documented and contributing to them can be daunting. Here's the CommandAPI's project structure for you!
10
10
11
11
## CommandAPI submodule folders
12
12
13
-
This is where all of the code is for the CommandAPI. The CommandAPI is a Maven project with multiple modules which each serve a different purpose:
13
+
This is where all the code is for the CommandAPI. The CommandAPI is a Maven project with multiple modules which each serves a different purpose:
14
14
15
-
-`commandapi-preprocessor` - The CommandAPI uses a bit of reflection to perform things which could not normally be done (for example, allowing custom commands in datapacks). Reflection is inherently unsafe and can lead to runtime errors if specific fields or methods are not present. The CommandAPI preprocessor project is a source annotation processor that checks all declared reflection calls and looks up at compile-time whether those calls are possible - if not, it prevents the CommandAPI from building. In short, it's a compile-time reflection checker.
15
+
-`commandapi-preprocessor` - The CommandAPI uses a bit of reflection to perform things which couldn’t normally be done (for example, allowing custom commands in datapacks). Reflection is inherently unsafe and can lead to runtime errors if specific fields or methods aren’t present. The CommandAPI preprocessor project is a source annotation processor that checks all declared reflection calls and looks up at compile-time whether those calls are possible - if not, it prevents the CommandAPI from building. In short, it's a compile-time reflection checker.
16
16
17
-
-`commandapi-x.x.x` - The CommandAPI needs to access various NMS methods in order to operate. These are implemented for the specific version given by `x.x.x`. For example, to support Minecraft `1.16.5`, the project is `commandapi-1.16.5`. The `NMS` class implementation is done in these version-specific files.
17
+
-`commandapi-x.x.x` - The CommandAPI needs to access various NMS methods to operate. These are implemented for the specific version given by `x.x.x`. For example, to support Minecraft `1.16.5`, the project is `commandapi-1.16.5`. The `NMS` class implementation is done in these version-specific files.
18
18
19
-
-`commandapi-core` - The main brains of the CommandAPI. This includes both the code that makes the CommandAPI run, as well as the API which developers can use.
19
+
-`commandapi-core` - The main brains of the CommandAPI. This includes both the code that makes the CommandAPI run, and the API which developers can use.
20
20
21
-
-`commandapi-vh` - The CommandAPI version handler. This is a super tiny project which simply links up all of the NMS version-specific files into the CommandAPI. This is only used for the actual running of the CommandAPI (e.g. the CommandAPI plugin or shading the CommandAPI). This ensures proper compile-time safety of NMS implementations.
21
+
-`commandapi-vh` - The CommandAPI version handler. This is a super tiny project that simply links up all the NMS version-specific files into the CommandAPI. This is only used for the actual running of the CommandAPI (e.g., the CommandAPI plugin or shading the CommandAPI). This ensures proper compile-time safety of NMS implementations.
22
22
23
-
-`commandapi-plugin` - It's the CommandAPI plugin! This is the project which is used for releases to both GitHub and Spigot. It's the CommandAPI all in one neat package, with a few extra features such as config-based command conversion for server owners (or other non-developers)
23
+
-`commandapi-plugin` - It's the CommandAPI plugin! This is the project used for releases to both GitHub and Spigot. It's the CommandAPI all in one neat package, with a few extra features such as config-based command conversion for server owners (or other non-developers)
24
24
25
25
-`commandapi-shade` - It's the CommandAPI, but in shade-able format. It has none of the features of the CommandAPI plugin variant and can be shaded into your own plugins. Effectively, it's `commandapi-core` + `commandapi-vh` with all of the `commandapi-x.x.x` NMS implementations included.
26
26
27
-
-`commandapi-annotations` - The CommandAPI annotations project is a small compile-time annotation processer that writes CommandAPI code for you. Using a compile-time annotation processor makes the server run so much faster than using a runtime-annotation processor, because annotation processing requires reflection to inspect class metadata.
27
+
-`commandapi-annotations` - The CommandAPI annotations project is a small compile-time annotation processor that writes CommandAPI code for you. Using a compile-time annotation processor makes the server run so much faster than using a runtime-annotation processor, because annotation processing requires reflection to inspect class metadata.
Copy file name to clipboardExpand all lines: docs/en/create-commands/arguments/arguments.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ List<Argument> arguments = new ArrayList<>();
26
26
arguments.add(newPlayerArgument("target"));
27
27
```
28
28
29
-
The String value is the node that is registered into Minecraft's internal command graph. This name is also used as a prompt that is shown to a player when they are entering the command.
29
+
The String value is the node registered into Minecraft's internal command graph. This name is also used as a prompt that is shown to a player when they are entering the command.
30
30
31
31
The CommandAPI is very flexible when it comes to registering arguments, and lets you use a number of different methods to suit your preference:
32
32
@@ -59,7 +59,7 @@ The CommandAPI is very flexible when it comes to registering arguments, and lets
59
59
60
60
## Argument Casting
61
61
62
-
To access arguments, they have to be casted to the type that the argument represents. The order of the arguments in the [`CommandArguments args`](./command-arguments) is the same as the order in which the arguments were declared.
62
+
To access arguments, they have to be cast to the type that the argument represents. The order of the arguments in the [`CommandArguments args`](./command-arguments) is the same as the order in which the arguments were declared.
Copy file name to clipboardExpand all lines: docs/en/create-commands/arguments/types/command-arguments.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,10 +10,10 @@ authors:
10
10
11
11

12
12
13
-
Command arguments allows users to provide an executable server command. The `CommandArgument` class lets you specify:
13
+
Command arguments allow users to provide an executable server command. The `CommandArgument` class lets you specify:
14
14
15
-
- Arbitrary commands - any command that the user has permissions to run can be provided.
16
-
- Restricted commands - only specific commands can be provided.
15
+
- Arbitrary commands – any command that the user has permissions to run can be provided.
16
+
- Restricted commands – only specific commands can be provided.
17
17
18
18
Using the `CommandArgument` will return a `CommandResult`, which contains a Bukkit `Command` instance representing the command to be executed, and a `String[]` of command arguments.
19
19
@@ -169,7 +169,7 @@ SuggestionsBranch.suggest(
169
169
/give apple
170
170
```
171
171
172
-
Ending the command argument with nothing is also equivalent to using `null`, for example the following suggestion branch allows any of the following commands:
172
+
Ending the command argument with nothing is also equivalent to using `null`, for example, the following suggestion branch allows any of the following commands:
173
173
174
174
```java
175
175
SuggestionsBranch.suggest(
@@ -186,7 +186,7 @@ SuggestionsBranch.suggest(
186
186
187
187
#### Empty suggestions
188
188
189
-
Empty suggestions that are provided using `ArgumentSuggestions.empty()` tell the `CommandArgument` to stop accepting further suggestions. This "ends" the command. Using the following example, this allows the user to enter `/give diamond` and only `/give diamond` - users cannot enter any other commands.
189
+
Empty suggestions that are provided using `ArgumentSuggestions.empty()` tell the `CommandArgument` to stop accepting further suggestions. This "ends" the command. Using the following example, this allows the user to enter `/give diamond` and only `/give diamond` - users can’t enter any other commands.
0 commit comments