Skip to main content

​
Overview

The Command API allows you to create custom commands for your PocketMine-MP server. Commands can be registered via plugin.yml or programmatically.

​
Creating Commands

​
Method 1: Using plugin.yml

Define commands in your plugin.yml:
plugin.yml
name: MyPlugin
main: MyPlugin\Main
version: 1.0.0
api: 5.0.0

commands:
  heal:
    description: Heal yourself
    usage: /heal
    permission: myplugin.heal
  broadcast:
    description: Broadcast a message
    usage: /broadcast <message>
    aliases: [bc, announce]
    permission: myplugin.broadcast
Then implement onCommand() in your main class: 
public function onCommand(CommandSender $sender, Command $command, string $label, array $args) : bool {
    switch($command->getName()) {
        case "heal":
            if($sender instanceof Player) {
                $sender->setHealth($sender->getMaxHealth());
                $sender->sendMessage("Healed!");
                return true;
            }
            return false;
            
        case "broadcast":
            if(count($args) === 0) {
                return false; // Shows usage
            }
            $this->getServer()->broadcastMessage(implode(" ", $args));
            return true;
    }
    return false;
}

​
Method 2: Extending Command Class

Create a custom command class:
Creating a custom command
<?php

namespace MyPlugin\commands;

use pocketmine\command\Command;
use pocketmine\command\CommandSender;
use pocketmine\player\Player;
use pocketmine\plugin\Plugin;
use pocketmine\plugin\PluginOwned;

class HealCommand extends Command implements PluginOwned {
    
    public function __construct(private Plugin $plugin) {
        parent::__construct(
            "heal",
            "Heal yourself",
            "/heal",
            ["hp"]
        );
        $this->setPermission("myplugin.heal");
    }
    
    public function execute(CommandSender $sender, string $commandLabel, array $args) {
        if(!$this->testPermission($sender)) {
            return false;
        }
        
        if(!($sender instanceof Player)) {
            $sender->sendMessage("This command must be used in-game");
            return false;
        }
        
        $sender->setHealth($sender->getMaxHealth());
        $sender->sendMessage("You have been healed!");
        return true;
    }
    
    public function getOwningPlugin() : Plugin {
        return $this->plugin;
    }
}
Register it in onEnable(): 
protected function onEnable() : void {
    $this->getServer()->getCommandMap()->register(
        "myplugin",
        new HealCommand($this)
    );
}

​
Command Class

​
Constructor

Creates a new command.
__construct()
public function __construct(
    string $name,
    Translatable|string $description = "",
    Translatable|string|null $usageMessage = null,
    array $aliases = []
)
​
name
string
required
Command name (without /)
​
description
string|Translatable
Command description shown in /help
​
usageMessage
string|Translatable|null
Usage message shown on error (default: “/commandname”)
​
aliases
string[]
Alternative names for the command
Example: 
$command = new MyCommand(
    "teleport",
    "Teleport to a player",
    "/teleport <player>",
    ["tp", "tele"]
);

​
execute()

Executes the command. Must be implemented by subclasses.
execute() : mixed
abstract public function execute(
    CommandSender $sender,
    string $commandLabel,
    array $args
)
​
sender
CommandSender
required
Who executed the command (Player, ConsoleCommandSender, etc.)
​
commandLabel
string
required
The exact label used (could be an alias)
​
args
string[]
required
Command arguments
Returns: mixed - Usually bool (true = success, false = show usage) Example: 
public function execute(CommandSender $sender, string $commandLabel, array $args) {
    if(!$this->testPermission($sender)) {
        return false;
    }
    
    if(count($args) < 1) {
        $sender->sendMessage("Usage: " . $this->getUsage());
        return false;
    }
    
    // Command logic here
    return true;
}

​
getName()

Gets the command name.
getName() : string
public function getName() : string
Returns: string - Command name

​
getAliases()

Gets command aliases.
getAliases() : array
public function getAliases() : array
Returns: string[] - Array of alias names

​
setAliases()

Sets command aliases.
setAliases(array $aliases) : void
public function setAliases(array $aliases) : void
​
aliases
string[]
required
Array of alias names

​
getDescription()

Gets the command description.
getDescription() : Translatable|string
public function getDescription() : Translatable|string
Returns: string|Translatable - Command description

​
setDescription()

Sets the command description.
setDescription(Translatable|string $description) : void
public function setDescription(Translatable|string $description) : void
​
description
string|Translatable
required
New description

​
getUsage()

Gets the usage message.
getUsage() : Translatable|string
public function getUsage() : Translatable|string
Returns: string|Translatable - Usage message

​
setUsage()

Sets the usage message.
setUsage(Translatable|string $usage) : void
public function setUsage(Translatable|string $usage) : void
​
usage
string|Translatable
required
New usage message

​
getPermissions()

Gets required permissions.
getPermissions() : array
public function getPermissions() : array
Returns: string[] - Array of permission nodes

​
setPermission()

Sets the permission required to use the command.
setPermission(?string $permission) : void
public function setPermission(?string $permission) : void
​
permission
string|null
required
Permission node, or null for no permission. Use ”;” to separate multiple permissions.
Example: 
$command->setPermission("myplugin.admin");
$command->setPermission("myplugin.use;myplugin.admin"); // Either permission
$command->setPermission(null); // No permission required

​
testPermission()

Tests if a sender has permission to use the command.
testPermission(CommandSender $target, ?string $permission = null) : bool
public function testPermission(CommandSender $target, ?string $permission = null) : bool
​
target
CommandSender
required
The sender to test
​
permission
string|null
Specific permission to test, or null to use command’s permission
Returns: bool - True if sender has permission Note: Automatically sends permission denied message to sender. Example: 
public function execute(CommandSender $sender, string $commandLabel, array $args) {
    if(!$this->testPermission($sender)) {
        return false; // Permission message already sent
    }
    
    // Command logic
    return true;
}

​
testPermissionSilent()

Tests permission without sending a message.
testPermissionSilent(CommandSender $target, ?string $permission = null) : bool
public function testPermissionSilent(CommandSender $target, ?string $permission = null) : bool
​
target
CommandSender
required
The sender to test
​
permission
string|null
Specific permission to test
Returns: bool - True if sender has permission

​
setPermissionMessage()

Sets the message shown when permission is denied.
setPermissionMessage(string $permissionMessage) : void
public function setPermissionMessage(string $permissionMessage) : void
​
permissionMessage
string
required
Permission denied message. Use <permission> as placeholder for permission node.
Example: 
$command->setPermissionMessage("You need <permission> to use this!");

​
broadcastCommandMessage()

Broadcasts a command message to administrators.
broadcastCommandMessage() : void
public static function broadcastCommandMessage(
    CommandSender $source,
    Translatable|string $message,
    bool $sendToSource = true
) : void
​
source
CommandSender
required
Command sender
​
message
string|Translatable
required
Message to broadcast
​
sendToSource
bool
Whether to send to the source (default: true)
Example: 
Command::broadcastCommandMessage(
    $sender,
    "Teleported {$player->getName()} to spawn"
);

​
CommandExecutor Interface

The CommandExecutor interface is implemented by PluginBase by default. It’s used for handling commands defined in plugin.yml.

​
onCommand()

Handles command execution.
onCommand() : bool
public function onCommand(
    CommandSender $sender,
    Command $command,
    string $label,
    array $args
) : bool
​
sender
CommandSender
required
Who executed the command
​
command
Command
required
The command object
​
label
string
required
The label used (could be alias)
​
args
string[]
required
Command arguments
Returns: bool - True if handled successfully, false to show usage

​
Complete Command Example

Advanced command example
<?php

namespace MyPlugin\commands;

use pocketmine\command\Command;
use pocketmine\command\CommandSender;
use pocketmine\player\Player;
use pocketmine\plugin\Plugin;
use pocketmine\plugin\PluginOwned;
use pocketmine\Server;

class TeleportCommand extends Command implements PluginOwned {
    
    public function __construct(private Plugin $plugin) {
        parent::__construct(
            "teleport",
            "Teleport to a player",
            "/teleport <player>",
            ["tp"]
        );
        $this->setPermission("myplugin.teleport");
        $this->setPermissionMessage("You don't have permission to teleport!");
    }
    
    public function execute(CommandSender $sender, string $commandLabel, array $args) {
        // Check permission
        if(!$this->testPermission($sender)) {
            return false;
        }
        
        // Must be a player
        if(!($sender instanceof Player)) {
            $sender->sendMessage("This command can only be used in-game");
            return false;
        }
        
        // Check arguments
        if(count($args) < 1) {
            $sender->sendMessage("Usage: " . $this->getUsage());
            return false;
        }
        
        // Find target player
        $targetName = $args[0];
        $target = Server::getInstance()->getPlayerExact($targetName);
        
        if($target === null) {
            $sender->sendMessage("Player '$targetName' not found!");
            return false;
        }
        
        // Teleport
        $sender->teleport($target->getLocation());
        $sender->sendMessage("Teleported to {$target->getName()}!");
        
        // Broadcast to admins
        Command::broadcastCommandMessage(
            $sender,
            "Teleported to {$target->getName()}"
        );
        
        return true;
    }
    
    public function getOwningPlugin() : Plugin {
        return $this->plugin;
    }
}
Register in main class: 
protected function onEnable() : void {
    $this->getServer()->getCommandMap()->register(
        $this->getName(),
        new TeleportCommand($this)
    );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us