Home

Welcome to PEMapModder's PocketMine Plugin Tutorials - Wiki.

This is a place for public contribution. Everyone can edit this wiki, but please keep in mind while editing that the wiki should be purely informative and neutral.

Introduction

This tutorial, unlike some other tutorials, goes on a test-then-explain basis. Because understand everything about PocketMine plugins require a deep knowledge in coding, this tutorial attempts to explain everything and make everything sensible, but sometimes I'll simply say Put it into your code, I won't explain. At these points, it would be because you don't have enough foundation knowledge. I'll explain once you have enough knowledge to understand.

Requirements

This tutorial is written for "general public", which means that it is expected to be read by everyone. However, there are some very basic things that you need to understand:

• How to run a basic PocketMine server that is joinable
• How to install plugins in PocketMine
• Basic knowledge in computers, such as the definition of files

Introduction to Coding

So let me explain what coding is. What comes up into your mind when I talk about "coding"? A programmer with a computer showing a black screen like that of a PocketMine console? A lot of meaningless characters and symbols?

Let's get the correct idea for "coding", at least in terms of PocketMine plugins. Here, we are going to write PHP code, which is a language fairly easy to leaen. Coding is a very logical and human-readable process. For evidence, let's take a look at this example line of code:

$player->sendMessage("Hello world!");

The above line means to sendMessage (send a message) to a player $player (we will look into variables later), with a message Hello world!.

So you can see, as long as you don't have phobia to monospace (the font type usually used for coding, which is also the font type used on PocketMine consoles), coding can actually be very easy and a lot of fun. It is just like working with redstone in Minecraft; you can make a simple lever-to-open-door setup, while you can also make a complicated Minecraft "calculator" or mob arenas. The only difference is that we don't have that much graphics, but words and symbols instead, in coding. However, obviously coding is much more powerful. 😀

The PHP official documentation said somewhere,

... is very dangerous because it allows execution of arbitrary PHP code. 

Being able to write and execute code gives you unlimited power. It brings you to the top of the world. After finally finishing a piece of software after a long time of trial and error, it would feel like you have flown through the stars, and now you are there, actualizing your dream. Are you ready for that?

Creating plugin.yml

Now let's create our first plugin. I call it MyPlugin.

First of all, at anywhere you like on your device, create an empty directory (folder, in case you don't understand) called MyPlugin. For the sake of convenience, I'll assume the directory is /plugins/MyPlugin. However, it would be convenient for testing if you create it in the plugins folder of your test server instead.

This MyPlugin directory will contain all the files required in a plugin, namely plugin.yml, src (source code) and resources.

The basic information of the plugin, including the plugin name, version and author (your name!), are specified in a file called plugin.yml. Here is an example:

name: MyPlugin
version: 1.0.0
author: YourName
api: 1.12.0
main: yourname\myplugin\MyPlugin

The first three lines are obvious, but I guess the last two lines need a bit explanation.

api is the PocketMine API version the plugin is compatible with. You don't need to understand this at the moment; simply copy that line. Basically it means whether the plugin can run on the current version PocketMine is running, but it is not related to the release code like 1.5.

main is the fully qualified name of your main class. Yes I know, you understand every word but you don't understand what I mean. That will be explained in the next section.

So, create a file called plugin.yml in /plugins/MyPlugin and copy the above things into it. For Windows users, I recommend using a program called Notepad++ to edit YAML files (and PHP files in the future, too).

Small trick: create a new file in Notepad++, copy the contents into it and click Save as. Browse to /plugins/MyPlugin and put plugin.yml as the file name, then hit enter.

First PHP File

Steady, calm down. It's not that scary.

Now, create the following directories:

/plugins/MyPlugin/src/
/plugins/MyPlugin/src/yourname/
/plugins/MyPlugin/src/yourname/myplugin/

Now, create an empty file at /plugins/MyPlugin/src/yourname/myplugin/, called MyPlugin.php. Found it familiar? Yes, it is the main: attribute in the plugin.yml mentioned above. Now let's talk about what all these mean.

In order to organize code better, PHP allows us to group our code using classes. The real concept of classes is fairly complicated, but for the moment, just assume it as the way to group code together.

The name of a class can be the combination of {A-Z a-z 0-9 _}, but it must not start with a number. It is the common practice of many developers that classes be named using the "camel hump" style, and the first character is always capital, like this:

Written in English => class name
Hello world => HelloWorld
my plugin => MyPlugin
My first PM plugin => MyFirstPMPlugin
Anti 3P => Anti3P
500 internal server error => _500InternalServerError or InternalServerError500

There is no strict rule about this, but if you name your class like my_plugin, people may not realize that it is a class. This confuses people when they are trying to help you.

Back to our plugin, we are going to name our main class something that describes it. So what is the best name? The plugin name, of course. The best thing about it is that it is unique. Each server run (technical term: PHP runtime) only loads one class with the same name. Having a unique class name is therefore important.

Hold on. This is a lie. What is that thing before the main class name?

It is called namespace. Starting in PHP 5.3.0, it is possible to group class names using namespaces.

The whole thing about namespaces and classes is like a filesystem. Namespaces are directories, and classes are files. In the same directory there cannot be two files or directories with the same name. However, if you put the files at different directories, there will be no conflict as long as you tell people which directory you are getting the file from. Vice versa for namespaces. Therefore, I was lying. A point to note is that the directory separator for files is / (fine, I know it is / or \ in Windows), but in PHP, the parts in namespaces are always separated by \, regardless of the operating system.

And the fact is, not only is it like a filesystem, but it is also based on a filesystem. You must put your PHP files in the correct path according to its full name (a.k.a. fully qualified name, i.e. namespace \ class name), with the namespace separator (\) changed to the directory separator, inside the source (src) folder. For example:

yourplugin\myplugin\MyPlugin => src/yourplugin/myplugin/MyPlugin.php

In the next section, we are going to fill the contents of MyPlugin.php.

unfinished page