Skip to main content

​
Quick Start Guide

This guide will help you get your PocketMine-MP server running and create your first simple plugin.

​
Prerequisites

Make sure you’ve completed the installation process before proceeding with this guide.

​
Starting Your Server

1

Navigate to Server Directory

Open a terminal and navigate to your PocketMine-MP installation directory:
cd /path/to/pocketmine
2

Start the Server

Run the start script:
./start.sh
3

Complete Setup Wizard

On first run, you’ll see the setup wizard:
[*] PocketMine-MP set-up wizard
[*] Please select a language:
Follow the prompts to configure:
  • Language
  • Server name
  • Port (default: 19132)
  • Maximum players
  • Game mode (Survival, Creative, Adventure)
  • Generate default world
4

Wait for Server to Start

You’ll see:
[Server thread/INFO]: Done (X.XXXs)! For help, type "help" or "?"
Your server is now running!

​
Connecting to Your Server

1

Open Minecraft Bedrock Edition

Launch Minecraft on your device (Windows 10/11, Android, iOS, Xbox, PlayStation, or Switch)
2

Go to Servers Tab

Navigate to the “Play” menu, then select the “Servers” tab
3

Add Server

Click “Add Server” and enter:
  • Server Name: Your choice
  • Server Address: localhost (if on same machine) or your server’s IP
  • Port: 19132 (default)
4

Join Server

Click on your server to join!
If connecting from another device, make sure port 19132 is open in your firewall and use your server’s local IP address (e.g., 192.168.1.100).

​
Basic Server Commands

Use these commands in the server console: 
# Stop the server
stop

# List online players
list

# Give a player operator permissions
op <player_name>

# Remove operator permissions
deop <player_name>

# Kick a player
kick <player_name> [reason]

# Ban a player
ban <player_name> [reason]

# Reload the server (not recommended during production)
reload

# View server status
status

# Save all worlds
save-all

​
Server Configuration

​
server.properties

Key settings in server.properties: 
# Server name shown in server list
server-name=PocketMine-MP Server

# Game mode (0=Survival, 1=Creative, 2=Adventure, 3=Spectator)
gamemode=0

# Difficulty (0=Peaceful, 1=Easy, 2=Normal, 3=Hard)
difficulty=1

# Maximum players
max-players=20

# Server port
server-port=19132

# Enable whitelist
white-list=off

# View distance
view-distance=8

​
pocketmine.yml

Advanced settings in pocketmine.yml: 
settings:
  # Server language
  force-language: false
  
  # Shutdown message
  shutdown-message: "Server closed"
  
  # Enable plugin profiling
  enable-profiling: false
  
  # AsyncTask workers (set to CPU cores)
  async-workers: auto

memory:
  # Global memory limit (MB, 0 to disable)
  global-limit: 0
  
  # Main thread hard memory limit (MB)
  main-hard-limit: 1024

​
Creating Your First Plugin

Let’s create a simple plugin that welcomes players when they join.

​
Plugin Structure

PocketMine-MP plugins can be:
  • Folder plugins (source code in folders)
  • PHAR plugins (compiled archives)
  • Script plugins (single PHP files)
For development, use folder plugins. For distribution, compile to PHAR using DevTools.

​
Script Plugin Example

Create a simple script plugin to get started quickly:
1

Create Plugin File

Navigate to your plugins directory and create WelcomePlugin.php:
cd plugins
touch WelcomePlugin.php
2

Write Plugin Code

Edit WelcomePlugin.php:
WelcomePlugin.php
<?php

namespace MyPlugins\WelcomePlugin;

use pocketmine\event\Listener;
use pocketmine\event\player\PlayerJoinEvent;
use pocketmine\plugin\PluginBase;
use pocketmine\utils\TextFormat;

/**
 * @main MyPlugins\WelcomePlugin\Main
 * @api 5.0.0
 * @name WelcomePlugin
 * @version 1.0.0
 */
class Main extends PluginBase implements Listener {
    
    public function onEnable(): void {
        $this->getServer()->getPluginManager()->registerEvents($this, $this);
        $this->getLogger()->info("WelcomePlugin enabled!");
    }
    
    public function onPlayerJoin(PlayerJoinEvent $event): void {
        $player = $event->getPlayer();
        $player->sendMessage(
            TextFormat::GREEN . "Welcome to the server, " . 
            $player->getName() . "!"
        );
        
        $this->getLogger()->info(
            $player->getName() . " joined the server"
        );
    }
}
3

Restart Server

Restart your server or use the reload command:
reload
You should see:
[Server thread/INFO]: [WelcomePlugin] WelcomePlugin enabled!
4

Test the Plugin

Join the server with a player. You should see a green welcome message!

​
Understanding the Plugin Code

Let’s break down the key components:

​
Plugin Metadata (DocBlock)

/**
 * @main MyPlugins\WelcomePlugin\Main
 * @api 5.0.0
 * @name WelcomePlugin
 * @version 1.0.0
 */
  • @main: Fully qualified class name of your main class
  • @api: Minimum API version required
  • @name: Plugin name (optional for script plugins)
  • @version: Plugin version (optional for script plugins)

​
Plugin Base Class

class Main extends PluginBase implements Listener
  • Extend PluginBase for basic plugin functionality
  • Implement Listener to listen to events

​
Event Registration

public function onEnable(): void {
    $this->getServer()->getPluginManager()->registerEvents($this, $this);
}
  • onEnable() is called when the plugin is enabled
  • Register the plugin as an event listener

​
Event Handling

public function onPlayerJoin(PlayerJoinEvent $event): void {
    $player = $event->getPlayer();
    $player->sendMessage("Welcome!");
}
  • Method name doesn’t matter for event handlers
  • Type hint the specific event class you want to handle
  • Access event data and perform actions

​
Folder Plugin Example

For more complex plugins, use the folder structure: 
plugins/
└── MyPlugin/
    ├── plugin.yml
    ├── src/
    │   └── MyPlugins/
    │       └── MyPlugin/
    │           └── Main.php
    └── resources/
        └── config.yml

​
plugin.yml

plugin.yml
name: MyPlugin
main: MyPlugins\MyPlugin\Main
version: 1.0.0
api: [5.0.0]
author: YourName
description: My awesome plugin

permissions:
  myplugin.command:
    description: Allow using the plugin command
    default: true

commands:
  mycommand:
    description: Test command
    usage: "/mycommand"
    permission: myplugin.command

​
Main.php

src/MyPlugins/MyPlugin/Main.php
<?php

namespace MyPlugins\MyPlugin;

use pocketmine\plugin\PluginBase;
use pocketmine\command\Command;
use pocketmine\command\CommandSender;

class Main extends PluginBase {
    
    public function onEnable(): void {
        $this->saveDefaultConfig();
        $this->getLogger()->info("MyPlugin enabled!");
    }
    
    public function onCommand(
        CommandSender $sender, 
        Command $command, 
        string $label, 
        array $args
    ): bool {
        if ($command->getName() === "mycommand") {
            $sender->sendMessage("Hello from MyPlugin!");
            return true;
        }
        return false;
    }
}

​
Installing Plugins from Poggit

1

Browse Poggit

Visit poggit.pmmp.io/plugins
2

Download Plugin

Find a plugin and download the .phar file
3

Install Plugin

Place the .phar file in your plugins/ directory:
cp DownloadedPlugin.phar /path/to/pocketmine/plugins/
4

Restart Server

Restart the server to load the plugin:
stop
./start.sh

​
Next Steps

Developer Documentation

Learn advanced plugin development

API Documentation

Browse the complete API reference

Example Plugin

Study a complete example plugin

DevTools

Build and package plugins

​
Common Issues

​
Plugin Not Loading

Check the server console for errors. Common issues:
  • Wrong API version in plugin metadata
  • Syntax errors in PHP code
  • Missing dependencies
  • Incorrect file permissions

​
Events Not Firing

Make sure you:
  1. Implement the Listener interface
  2. Register events in onEnable()
  3. Type-hint the correct event class

​
Cannot Connect to Server

Check:
  • Server is running (no errors in console)
  • Using correct IP and port
  • Firewall allows UDP traffic on port 19132
  • Server and client are on compatible versions
Join the PocketMine-MP Discord for help from the community!

Build docs developers (and LLMs) love

Get started for freeTalk to us