Skip to content

Commit 383dd4c

Browse files
MC-XiaoHeiMC-XiaoHei
committed
feat: finish utils part
1 parent eb84a7f commit 383dd4c

File tree

5 files changed

+247
-0
lines changed

5 files changed

+247
-0
lines changed

‎docs/en/utils/conversion.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
order: 1
3+
authors:
4+
- JorelAli
5+
- DerEchtePilz
6+
- willkroboth
7+
---
8+
9+
# Command conversion
10+
11+
:::info
12+
13+
If you're a server owner, you're probably lost! This section is for developer command conversion. If you're looking for how to convert plugins with the `config.yml` file, you want [Configuration for server owners](../user-setup/config#plugins-to-convert).
14+
15+
:::
16+
17+
The CommandAPI has the ability to convert plugin commands to vanilla Minecraft commands using its `config.yml`'s `plugins-to-convert` option. Nevertheless, the API for command conversion is not hidden and you're free to use it as you see fit!
18+
19+
Before you continue, let's clear up a few naming conventions which is used in the following sections!
20+
21+
- **Target plugin** - This refers to a non-CommandAPI plugin which registers normal Bukkit commands. This typically uses the old `boolean onCommand(CommandSender ... )` method
22+
- **Your plugin** - This refers to your plugin, the one that uses the CommandAPI and wants to add compatibility to a target plugin
23+
24+
## Entire plugins
25+
26+
To register all commands that are declared by a target plugin, the `Converter.convert(Plugin)` method can be used. This attempts to register all commands declared in a target plugin's `plugin.yml` file, as well as any aliases or permissions stated in the `plugin.yml` file.
27+
28+
::::tip Example – Converting commands for a target plugin
29+
30+
Say you have some `plugin.yml` file for a target plugin that adds some basic functionality to a server. The target plugin in this example is called "TargetPlugin":
31+
32+
```yaml
33+
name: TargetPlugin
34+
main: some.random.package.Main
35+
version: 1.0
36+
commands:
37+
gmc:
38+
aliases: gm1
39+
gms:
40+
i:
41+
permission: item.permission
42+
```
43+
44+
As you can see, it declares 3 commands: `/gmc`, `/gms` and `/i`. We can now begin writing your plugin that uses the CommandAPI converter. We will call this plugin "YourPlugin":
45+
46+
:::tabs
47+
===Java
48+
<<< @/../reference-code/src/main/java/utils/Conversion.java#simpleConvertExample
49+
===Kotlin
50+
<<< @/../reference-code/src/main/kotlin/utils/Conversion.kt#simpleConvertExample
51+
:::
52+
53+
When this is run, the commands `/gmc`, `/gm1`, `/gms` and `/i` will all be registered by the CommandAPI.
54+
55+
::::
56+
57+
## Only specific commands
58+
59+
In addition to converting all commands from a target plugin, the CommandAPI allows you to convert single commands at a time using the following methods from the `Converter` class:
60+
61+
```java
62+
public static convert(Plugin plugin, String cmdName);
63+
public static convert(Plugin plugin, String cmdName, List<Argument> arguments);
64+
public static convert(Plugin plugin, String cmdName, Argument... arguments);
65+
```
66+
67+
In these commands, the `plugin` refers to the plugin which has the command you want to convert and `cmdName` is the name of the command declared in the target plugin's `plugin.yml` file (just the main command, not the aliases!).
68+
69+
The `List<Argument>` or `Argument...` can be used to provide argument checks that lets you apply the command UI to a bukkit command.
70+
71+
::::tip Example – Converting EssentialsX's speed command
72+
73+
Say we want to convert EssentialsX's `/speed` command using the CommandAPI. The `plugin.yml` entry for the `/speed` command is the following:
74+
75+
```yaml
76+
speed:
77+
description: Change your speed limits.
78+
usage: /<command> [type] <speed> [player]
79+
aliases: [flyspeed,eflyspeed,fspeed,efspeed,espeed,walkspeed,ewalkspeed,wspeed,ewspeed]
80+
```
81+
82+
From this, we can determine that there are the following commands, where "walk" and "fly" are the different types that the command can take:
83+
84+
```mccmd
85+
/speed <speed>
86+
/speed <speed> <target>
87+
/speed <walk/fly> <speed>
88+
/speed <walk/fly> <speed> <target>
89+
```
90+
91+
With the EssentialsX plugin, the `<speed>` value can only take numbers between 0 and 10. As such, we'll ensure to apply these limits using the `IntegerArgument`. In addition, since the speed type can only be "walk" or "fly", we'll add that to our converter as well using a `MultiLiteralArgument`:
92+
93+
:::tabs
94+
===Java
95+
<<< @/../reference-code/src/main/java/utils/Conversion.java#convertSpeedCommandExample
96+
===Kotlin
97+
<<< @/../reference-code/src/main/kotlin/utils/Conversion.kt#convertSpeedCommandExample
98+
:::
99+
100+
![An image showing /execute run for EssentialsX's /speed command](/images/speed.gif)
101+
102+
::::

docs/en/utilities/index.md renamed to docs/en/utils/index.md

File renamed without changes.

‎docs/en/utils/reload.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
order: 2
3+
authors:
4+
- JorelAli
5+
---
6+
7+
# Plugin reloading
8+
9+
Formally, the CommandAPI **does not** support plugin reloading. This includes, but is not limited to:
10+
11+
* The `/reload` command which reloads all plugins on the server
12+
* Plugin reloading plugins, such as [PlugMan](https://dev.bukkit.org/projects/plugman)
13+
* Any form of plugin enabling/disabling process for plugins which register commands via the CommandAPI
14+
15+
In general, using the `/reload` command is _not advised_. Here's some useful resources from various Bukkit/Spigot/Paper developers:
16+
17+
* Maddy Miller (WorldEdit creator):
18+
* [Why you should never /reload on Spigot, Bukkit, and Paper](https://madelinemiller.dev/blog/problem-with-reload/)
19+
* Bukkit Forums:
20+
* [Is /reload that bad](https://bukkit.org/threads/is-reload-that-bad.129514/)
21+
* [Petition to remove the /reload command](https://bukkit.org/threads/petition-to-remove-the-reload-command.43212/)
22+
* Spigot Forums:
23+
* [What's with the /reload command?](https://www.spigotmc.org/threads/whats-with-the-reload-command.344458/)
24+
* [Let's kill /reload, or make it better.](https://www.spigotmc.org/threads/lets-kill-reload-or-make-it-better.35611/)
25+
26+
The CommandAPI is _not like normal Bukkit/Spigot/Paper plugins_. It directly accesses all of the nitty-gritty Vanilla Minecraft code to convert and expose Minecraft's internal command framework into a Bukkit-API friendly interface for you to use. As the CommandAPI hooks directly into Vanilla Minecraft code, and `/reload` is a Bukkit feature, using `/reload` can cause Vanilla Minecraft's internal system to become unstable. If you are having issues with `/reload`, seriously reconsider shutting your server down correctly and restarting it, instead of running `/reload`.
27+
28+
Despite this, there is one way to get reloading to work using the `onDisable()` method in your plugin. If you register a command in your `onLoad()` or `onEnable()` method, by unregistering the command in your `onDisable()` method, this allows the CommandAPI to properly register the command again when the server reloads.
29+
30+
:::danger Developer's Note:
31+
32+
Despite the fact that you can do this, I cannot stress enough that **this is not recommended**, due to the fact that **functions/tags in datapacks do not work with `/reload`, even if you unregister the command**.
33+
34+
:::
35+
36+
:::tip Example – Allowing a command to work with `/reload`
37+
38+
In this example, we add support for reloading the server via `/reload` by unregistering the command in the `onDisable()` method. Note that force-unregistering is not required for this:
39+
40+
```java
41+
public class MyPlugin extends JavaPlugin {
42+
@Override
43+
public void onEnable() {
44+
new CommandAPICommand("ping")
45+
.executes((sender, args) -> {
46+
sender.sendMessage("Pong!");
47+
})
48+
.register();
49+
}
50+
51+
@Override
52+
public void onDisable() {
53+
CommandAPI.unregister("ping");
54+
}
55+
}
56+
```
57+
58+
:::

‎reference-code/src/main/java/utils/Conversion.java‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
package utils;
2+
3+
import dev.jorel.commandapi.Converter;
4+
import dev.jorel.commandapi.arguments.IntegerArgument;
5+
import dev.jorel.commandapi.arguments.MultiLiteralArgument;
6+
import dev.jorel.commandapi.arguments.PlayerArgument;
7+
import org.bukkit.Bukkit;
8+
import org.bukkit.plugin.java.JavaPlugin;
9+
10+
class Conversion {
11+
// #region simpleConvertExample
12+
public class YourPlugin extends JavaPlugin {
13+
@Override
14+
public void onEnable() {
15+
Converter.convert((JavaPlugin) Bukkit.getPluginManager().getPlugin("TargetPlugin"));
16+
// Other code goes here...
17+
}
18+
}
19+
// #endregion simpleConvertExample
20+
21+
{
22+
// #region convertSpeedCommandExample
23+
JavaPlugin essentials = (JavaPlugin) Bukkit.getPluginManager().getPlugin("Essentials");
24+
25+
// /speed <speed>
26+
Converter.convert(essentials, "speed", new IntegerArgument("speed", 0, 10));
27+
28+
// /speed <target>
29+
Converter.convert(essentials, "speed", new PlayerArgument("target"));
30+
31+
// /speed <walk/fly> <speed>
32+
Converter.convert(essentials, "speed",
33+
new MultiLiteralArgument("modes", "walk", "fly"),
34+
new IntegerArgument("speed", 0, 10)
35+
);
36+
37+
// /speed <walk/fly> <speed> <target>
38+
Converter.convert(essentials, "speed",
39+
new MultiLiteralArgument("modes", "walk", "fly"),
40+
new IntegerArgument("speed", 0, 10),
41+
new PlayerArgument("target")
42+
);
43+
// #endregion convertSpeedCommandExample
44+
}
45+
}

‎reference-code/src/main/kotlin/utils/Conversion.kt‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
package utils
2+
3+
import dev.jorel.commandapi.Converter
4+
import dev.jorel.commandapi.arguments.IntegerArgument
5+
import dev.jorel.commandapi.arguments.MultiLiteralArgument
6+
import dev.jorel.commandapi.arguments.PlayerArgument
7+
import org.bukkit.Bukkit
8+
import org.bukkit.plugin.java.JavaPlugin
9+
10+
fun conversion() {
11+
// #region simpleConvertExample
12+
class YourPlugin : JavaPlugin() {
13+
override fun onEnable() {
14+
Converter.convert(Bukkit.getPluginManager().getPlugin("TargetPlugin") as JavaPlugin)
15+
// Other code goes here...
16+
}
17+
}
18+
// #endregion simpleConvertExample
19+
20+
// #region convertSpeedCommandExample
21+
val essentials = Bukkit.getPluginManager().getPlugin("Essentials") as JavaPlugin
22+
23+
// /speed <speed>
24+
Converter.convert(essentials, "speed", IntegerArgument("speed", 0, 10))
25+
26+
// /speed <target>
27+
Converter.convert(essentials, "speed", PlayerArgument("target"))
28+
29+
// /speed <walk/fly> <speed>
30+
Converter.convert(essentials, "speed",
31+
MultiLiteralArgument("modes", "walk", "fly"),
32+
IntegerArgument("speed", 0, 10)
33+
)
34+
35+
// /speed <walk/fly> <speed> <target>
36+
Converter.convert(essentials, "speed",
37+
MultiLiteralArgument("modes", "walk", "fly"),
38+
IntegerArgument("speed", 0, 10),
39+
PlayerArgument("target")
40+
)
41+
// #endregion convertSpeedCommandExample
42+
}

0 commit comments

Comments
 (0)