PlaceholderAPI

A powerful and flexible placeholder plugin for PocketMine-MP Minecraft servers, enabling dynamic data integration in chat, scoreboards, and other plugins.

PlaceholderAPI allows server administrators to use dynamic placeholders (e.g., %player_name%, %server_online_players%) to display real-time information about players, server status, and time. It includes built-in expansions and supports custom ones for developers to extend functionality.

• Dynamic Placeholders: Replace placeholders with real-time data.
• Built-in Expansions: Player, server, and time data out of the box.
• Player Data Tracking: Tracks session data like join time.
• Commands: Manage and test placeholders easily.
• Developer-Friendly: Extendable with custom expansions.

• /papi reload: Reloads the plugin configuration.
• /papi list: Lists all registered expansions.
• /papi parse <text>: Parses placeholders in the given text.
• /papi test <expansion> <placeholder>: Tests a specific placeholder.

Permission: placeholderapi.admin (required for commands).

• %player_name%: Player's username.
• %player_display_name%: Player's display name.
• %player_ping%: Player's ping.
• %player_health%: Current health.
• %player_max_health%: Maximum health.
• %player_food%: Food level.
• %player_level%: World name.
• %player_gamemode%: Current gamemode.
• %player_ip%: Player's IP address.
• %player_x%, %player_y%, %player_z%: Coordinates.
• %player_is_op%: Operator status (true/false).
• %player_name_format%: Rank-based name color (requires RankSystem).
• %player_session_time%: Session duration (HH:MM:SS).

• %server_name%: Server MOTD.
• %server_ip%: Server IP.
• %server_port%: Server port.
• %server_max_players%: Max player limit.
• %server_online_players%: Current online players.
• %server_version%: Server version.
• %server_tps%: Ticks per second.
• %server_load%: Tick usage percentage.

• %time_current%: Current time (e.g., 14:30:45).
• %time_date%: Current date (e.g., 2025-07-23).
• %time_datetime%: Date and time (e.g., 2025-07-23 14:30:45).
• %time_timestamp%: Unix timestamp.

To use placeholders in your plugin, call the parsePlaceholders method from the PlaceholderAPI class. This method processes a string containing placeholders and replaces them with their corresponding values.

public function parsePlaceholders(string $text, ?Player $player = null): string

• Parameters:
  • $text: The input string containing placeholders (e.g., Hello %player_name%!).
  • $player: An optional Player object for player-specific placeholders. Pass null for non-player-specific placeholders (e.g., server or time).
• Returns: The string with placeholders replaced by their values.

The method uses a regular expression to match placeholders in the format %identifier_placeholder% (e.g., %player_name%). It then calls the onPlaceholderRequest method of the corresponding expansion to retrieve the value. If the placeholder or expansion is invalid, the original placeholder text is returned unchanged.

use MohamadRZ4\Placeholder\PlaceholderAPI;
use pocketmine\player\Player;

function displayWelcomeMessage(Player $player): void {
    $placeholderAPI = PlaceholderAPI::getAPI();
    if ($placeholderAPI !== null) {
        $message = $placeholderAPI->parsePlaceholders(
            "Welcome %player_name% to %server_name%! Time: %time_current%",
            $player
        );
        $player->sendMessage($message);
    }
}

Output (example):

Welcome Steve to MyServer! Time: 14:30:45

• Ensure the PlaceholderAPI plugin is enabled and loaded before calling getAPI().
• Placeholders are case-sensitive.
• For player-specific placeholders, always pass a valid Player object.
• Non-existent placeholders remain unchanged in the output string.

Create custom expansions by extending PlaceholderExpansion. Implement required methods: getIdentifier, getVersion, getAuthor, and onPlaceholderRequest.

<?php

namespace MyPlugin\Expansion;

use MohamadRZ4\Placeholder\expansion\PlaceholderExpansion;
use MohamadRZ4\Placeholder\PlaceholderAPI;
use pocketmine\player\Player;

class PlayTimeExpansion extends PlaceholderExpansion {

    public function getIdentifier(): string {
        return "playtime";
    }

    public function getVersion(): string {
        return "1.0.0";
    }

    public function getAuthor(): string {
        return "YourName";
    }

    public function onPlaceholderRequest(?Player $player, string $placeholder): ?string {
        if ($player === null) {
            return null;
        }

        if ($placeholder === "total_hours") {
            $joinTime = $this->plugin->getPlayerData($player->getName())["join_time"] jQuery32106993173049449735_1753261601640 time();
            $totalSeconds = time() - $joinTime;
            $hours = floor($totalSeconds / 3600);
            return (string)$hours;
        }

        return null;
    }

    public function onRegister(PlaceholderAPI $plugin): void {
        parent::onRegister($plugin);
    }
}

Register the expansion:

$placeholderAPI = PlaceholderAPI::getAPI();
if ($placeholderAPI !== null) {
    $placeholderAPI->registerExpansion(new PlayTimeExpansion());
}

Use %playtime_total_hours% to display total hours played.

• Placeholders are case-sensitive (e.g., %player_name%).
• Updates every 20 ticks (1 second) for real-time data.
• Ensure dependencies are installed for full functionality.