Tutorial Updating a Plugin to Work with Different APIs (The Manual Way)

Updating a plugin to be compatible with a new API can be as easy as changing/adding the version number in the plugin.yml file or as complicated as having to rewrite major sections of the plugin code (possibly all of it). So far, most of the plugins that I have updated to work with 3.0.0-ALPHA7 have needed some small changes, but nothing major. There are some tools available that can automate parts of this process but it's not likely to find one which can completely fix all compatibility problems with every bit of code.

Requirements
There are some things that you need and things to be familiar with before attempting these instructions. Otherwise, you may find this very difficult.

• How to access your PMMP server's console
• How to move files between your computer and your PMMP server
• How to get plugin source code from GitHub (or other locations)
• Some exposure to PHP programming (or some other Object Oriented program language)
• A copy of the DevTools plugin (source found here)
• A good text editor (I use Notepad++)

Getting Started
Prepare your server environment for testing. If your server is constantly populated with other players, then it may be best to setup a test environment that only you have access to as this process will cause the server to stop and start several times.

You will need to know the API version number for the server software you are using. At the time of writing, the master branch was at 3.0.0-ALPHA7. You can find this by starting your server or using the /version command if your server is already running.



Note: The larger the gap is between the API version of your plugin and the API version of your server software, the more likely it is that this process will be more difficult.

Once you have the version information for your server software, you need to install the appropriate version of DevTools from the source above. This will save a lot of time while you are debugging. (Thanks for this info Thunder33345)

Next you will need a copy of the contents of the plugin's phar file. You can typically get this by downloading the source from GitHub. This needs to be on your local machine so that you can edit the files. I will be updating SimpleHG by Kaleb Wasmuth (source code is here).

First Plugin Changes
To make an outdated plugin load with your current API, you will need to change a line in plugin.yml that says api. This does not guarantee that the plugin will work. For example, to get a plugin to load with API 3.0.0-ALPHA7 your api line would need to look like this:

Code:

api: [3.0.0-ALPHA7]

For SimpleHG, this is found on line 21


The updated version looks like this:



Start/Restart the Server
At this point we are ready to see what happens when the plugin loads. Start/Restart your server and watch the console output to see if the plugin actually loads.



Notice that my DevTools plugin has the "Incompatible API version" error but SimpleHG does not.

Handling Errors
Next you need to watch for any errors caused by the plugin. With SimpleHG an error was immediately generated after loading the plugin.



This is where things can get tricky but don't let this overwhelm you. Many times, the error you receive will actually tell you what's wrong instead of leaving you out to dry. Here we are told that there is a problem with something in the Main.php file. We can see this at the end of the Fatal error message.

Code:

in phar:///etc/pmmp/plugins/SimpleHG.phar/src/SimpleHG/Main.php on line 58

Each error message will be a bit different and you will need to decipher each problem independently. When you have a "crash" like this, a log file is generated in a folder called crashdumps. You can look at this log to get a clearer understanding of the error.



If we look more closely at the error message on line 3, it tells us that:

Code:

Declaration of SimpleHG\Main::onCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, $label, array $args) must be compatible with pocketmine\command\CommandExecutor::onCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool

This is where being familiar with php and/or other object oriented languages will be useful. With this specific error, the problem is that the plugin is trying to do something with a function that is defined in the PMMP source, specifically the 'onCommand' function. If we search through Main.php of the SimpleHG plugin, we find that on line 640, there is a declaration of the onCommand function. Let's look at our error message again, specifically the second half.

Code:

must be compatible with pocketmine\command\CommandExecutor::onCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool

The error is telling us that something with how this function is written, is not compatible with the function in the PMMP source and that the declaration of this function should look like this:

Code:

public function onCommand(CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool

But the one in Main.php looks like this:

Code:

public function onCommand(CommandSender $sender, Command $command, $label, array $args)

Careful comparison shows that we are missing the word 'string' before '$label' and ': bool' after the closing parenthesis. If we change our code to match it should look like this:



Once you make changes to fix an error, you need to:

• Upload your plugin changes
• Start/Restart the server
• Look for more errors

After restarting the server, with SimpleHG you will get something like this:


Notice that SimpleHG was enabled and that the server is still running. At this point, you should be able to connect to your server from the game.

We're done...... Right?
Unfortunately, no. If you haven't gained an appreciation for plugin developers by this point, then the next part should help you with that. Now you get to do it all over again with each of the plugin's functions. This means that you have to try using all of the plugins features and see if anything is broken or causes the server to crash.

This process can be long and tedious or short and sweet depending on the plugin. With SimpleHG this will require that you setup an area for the match, update the config.yml file, and try playing several games with all the different options enabled/disabled.

Hint: SimpleHG still has a problem.

As you find each error, you will need to take similar steps to resolving them. In some cases, you may find that entire sections of code need to be rewritten. Don't be discouraged though. This process gets easier each time you go through it.

Create the Plugin.phar file
To do this, you will need the DevTools plugin installed on your server. This information can be found in the DevTools ReadMe but has been included here for ease of access.

The Easy Way
While your server is started, run the /makeplugin command. For example, to build the SimpleHG plugin you would use this:

Code:

/makeplugin SimpleHG

When DevTools is finished, the phar file will be in the plugins/DevTools folder

The Hard Way
If you have not installed the DevTools plugin, or you don't want to make your plugin from inside the server, the other way is to use the ConsoleScript.php file from the DevTools source code. It can be found in the src/DevTools folder. Upload this file to your server then change the file paths in the following command and execute it outside of the PMMP software:

Code:

php -dphar.readonly=0 path/to/ConsoleScript.php --make path/to/your/plugin/sourcecode --out path/to/put/your/plugin.phar

​

For example, my test server has the PMMP server in /etc/pmmp and I have a copy of the ConsoleScript.php file at /etc/pmmp/plugins/DevTools.​

Code:

php -dphar.readonly=0 /etc/pmmp/plugins/DevTools/ConsoleScript.php --make /etc/pmmp/plugins/SimpleHG --out /etc/pmmp/plugins/SimpleHG.phar

Note: If you are having trouble with this, check the README for DevTools.​

 

Wow, you really put some amazing effort in this thread. Bravo. You've made a great tutorial on this, finally someone who explains that updating a plugin is not just changing an Api number and boom, done. Honestly, Very well done on this. Good job.

 

I was not aware of that feature in DevTools. I will definitely add that info shortly.

 

Thanks for this, i don't really know how to code using someone else's api but this made it very easy to understand. Will most of it just be fixing functions in the plugins?

 

There is no straight answer to your question. Each plugin will need to be evaluated on an individual basis and there are several factors that will affect what will be necessary to complete the process.

The first factor to consider is how much of a gap there is between the API version the plugin was written for and the API version of your server. If this is a significant difference (eg. Plugin API is v1.0.0 and server API version is 3.0.0-ALPHA5) you may be better off just writing the plugin from scratch or looking for another plugin that performs similar function.

The next factor is how large the plugin is. The more code there is in a plugin, the more likely you are to have problems. Extensive plugins may also make use of more features from the API which is more potential for problems.

While there are some other things that can affect what changes will be necessary, those two factors are (IMHO) the two largest. If you hit a snag, you can always ask in the plugin development forums for help. If you do, make sure to post what you have already tried and the code you are having problems with.

 

I don't understand why isn't this working..

Declaration of ServerAuth\Commands\Commands:nCommand($sender, $command, string $label, array $args): bool must be compatible with pocketmine\command\CommandExecutor:nCommand(pocketmine\command\CommandSender $sender, pocketmine\command\Command $command, string $label, array $args): bool
File: ServerAuth_v2.13.phar/src/ServerAuth/Commands/Commands
Line: 24
Type: E_COMPILE_ERROR

I did replace the code exactly as it said, but it does not work and I'm confused, i tried copy and pasting the exactly as it said as well and it didnt work.

[15] use pocketmine\command\CommandExecutor;
[16] use pocketmine\command\CommandSender;
[17] use pocketmine\Player;
[18] use pocketmine\Server;
[19] use pocketmine\plugin\PluginBase;
[20]
[21] use ServerAuth\ServerAuth;
[22] use ServerAuth\Tasks\MySQLTask;
[23]
[24] class Commands extends PluginBase implements CommandExecutor {
[25]
[26] public function __construct(ServerAuth $plugin){
[27] $this->plugin = $plugin;
[28] }
[29]
[30] public function onCommand($sender, $command, string $label, array $args): bool {
[31] $fcmd = strtolower($cmd->getName());
[32] switch($fcmd){
[33] case "serverauth":
[34] if(isset($args[0])){

 

I did that as well, it didn't work. I said that when i posted my problems. The problem is that the return type changes and I am used to java so i didnt know what that was and ignored it lol.

 

Lmao! I have Android device and for update the API version i use this aplications from Play Store:

- AIDE Web (For edit Code)
-Phar (For compile phar)

For extract phar i use a devtools plugin.
Too search diferent phar versions of pocketmine with diferent API
Example: 3.0.0-ALPHA4 or 3.0.0-ALPHA5 etc etc for extract the phar.
It work fine for me.

 

No, that's just a really outdated plugin

 

There is 1 way, but I gurantee I am gonna get hate for saying it and you shouldnt really use it. Its good to learn the manual way. I was like you when I came, I aksed the same thing xD. But now I learnt and could update an API as my life depended on it xD

 

Wouldn't recommend this... But if your plugin is small and has less features just use DevTools