PlaceholderAPI

PlaceholderAPI Skill

PlaceholderAPI is a plugin for Spigot servers that allows server owners to display information from various plugins with a uniform format. It enables dynamic text replacement through expansions, allowing plugins to provide and consume placeholder values like %player_name% or %server_online%.

Overview

PlaceholderAPI has been downloaded over 1,700,000 times on Spigot and has been used concurrently on over 45,000 servers, making it a must-have for servers of any type or scale. With over 240+ expansions, it supports a wide variety of plugins including Essentials, Factions, LuckPerms, and Vault.

When to Use This Skill

Trigger this skill when:

• Creating a PlaceholderExpansion - Implementing internal or external placeholder expansions for your plugin
• Integrating PlaceholderAPI - Adding placeholder parsing capability to an existing plugin
• Configuring build dependencies - Setting up Maven/Gradle dependencies for PlaceholderAPI
• Troubleshooting expansions - Debugging NoClassDefFoundError, expansion loading failures, or registration issues
• Implementing relational placeholders - Creating placeholders that compare values between two players
• Using PlaceholderAPI programmatically - Parsing placeholders dynamically in Java code
• Learning eCloud commands - Downloading, listing, or managing expansions from the cloud repository

Quick Reference

1. Maven Dependency Setup

<repositories>
    <repository>
        <id>placeholderapi</id>
        <url>https://repo.extendedclip.com/releases/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>me.clip</groupId>
        <artifactId>placeholderapi</artifactId>
        <version>2.11.6</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

2. Gradle Dependency Setup

repositories {
    maven { url 'https://repo.extendedclip.com/releases/' }
}

dependencies {
    compileOnly 'me.clip:placeholderapi:2.11.6'
}

3. Basic PlaceholderExpansion Structure

package at.helpch.placeholderapi.example.expansion;

import me.clip.placeholderapi.expansion.PlaceholderExpansion;
import org.bukkit.OfflinePlayer;
import org.jetbrains.annotations.NotNull;

public class SomeExpansion extends PlaceholderExpansion {

    @Override
    @NotNull
    public String getAuthor() {
        return "Author"; // Required: Expansion author name
    }

    @Override
    @NotNull
    public String getIdentifier() {
        return "example"; // Required: Used as %example_param%
    }

    @Override
    @NotNull
    public String getVersion() {
        return "1.0.0"; // Required: Expansion version
    }

    @Override
    public String onRequest(OfflinePlayer player, @NotNull String params) {
        if (params.equalsIgnoreCase("placeholder1")) {
            return "text1";
        }
        return null; // Return null for invalid placeholders
    }
}

4. Internal Expansion with Plugin Integration (Recommended)

package at.helpch.placeholderapi.example.expansion;

import at.helpch.placeholderapi.example.SomePlugin;
import me.clip.placeholderapi.expansion.PlaceholderExpansion;
import org.bukkit.OfflinePlayer;
import org.jetbrains.annotations.NotNull;

public class SomeExpansion extends PlaceholderExpansion {

    private final SomePlugin plugin;

    public SomeExpansion(SomePlugin plugin) {
        this.plugin = plugin;
    }

    @Override
    @NotNull
    public String getAuthor() {
        return String.join(", ", plugin.getDescription().getAuthors());
    }

    @Override
    @NotNull
    public String getIdentifier() {
        return "example";
    }

    @Override
    @NotNull
    public String getVersion() {
        return plugin.getDescription().getVersion();
    }

    @Override
    public boolean persist() {
        return true; // Keep expansion loaded on reload
    }

    @Override
    public String onRequest(OfflinePlayer player, @NotNull String params) {
        if (params.equalsIgnoreCase("config_value")) {
            return plugin.getConfig().getString("path.value", "default");
        }
        return null;
    }
}

5. Registering Internal Expansion in Plugin

package at.helpch.placeholderapi.example;

import at.helpch.placeholderapi.example.expansion.SomeExpansion;
import org.bukkit.Bukkit;
import org.bukkit.plugin.java.JavaPlugin;

public class SomePlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        if (Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")) {
            new SomeExpansion(this).register();
        }
    }
}

6. Parsing Placeholders in Code

import me.clip.placeholderapi.PlaceholderAPI;

// Parse with player context
String parsed = PlaceholderAPI.setPlaceholders(player, "Hello %player_name%!");
player.sendMessage(parsed);

// Parse without player (server-level placeholders only)
String serverInfo = PlaceholderAPI.setPlaceholders(null, "Online: %server_online%");

7. plugin.yml Configuration

name: MyPlugin
version: 1.0.0
main: com.example.MyPlugin
author: Author
softdepend:
  - PlaceholderAPI

8. Handling Multiple Parameters

@Override
public String onRequest(OfflinePlayer player, @NotNull String params) {
    // %example_param1% -> params = "param1"
    // %example_section_value% -> params = "section_value"

    if (params.startsWith("info_")) {
        String type = params.substring(5); // Remove "info_" prefix
        return getInfo(type);
    }

    switch (params.toLowerCase()) {
        case "name":
            return player != null ? player.getName() : "None";
        case "uuid":
            return player != null ? player.getUniqueId().toString() : "None";
        default:
            return null;
    }
}

Reference Files

This skill includes comprehensive documentation in references/:

Key Concepts

Placeholder Syntax

Important: When using placeholders within the Animations expansion text, you must use the bracket variant {player_name} instead of %player_name%.

Expansion Types

The onRequest Method

• Purpose: Called by PlaceholderAPI when a matching placeholder is parsed
• params parameter: Contains text after the underscore (e.g., "param" in %example_param%)
• Return values:
  • null → Placeholder is invalid
  • "" (empty string) → Valid placeholder with no value
  • Any other string → The replacement value

persist() Method

• Purpose: Controls whether expansion stays loaded during /papi reload
• Return true: Required for internal expansions to prevent unregistration
• Return false: Expansion will be unregistered on reload (default for external)

Common Commands

Parse Commands

eCloud Commands

Expansion Management

Resources

Official Links

Popular Expansions

Download from eCloud using /papi ecloud download <name>:

Common Errors and Solutions

NoClassDefFoundError: com/google/gson/Gson

[PlaceholderAPI] Failed to load Expansion class <expansion> (Is a dependency missing?)
[PlaceholderAPI] Cause: NoClassDefFoundError <path>

Cause: Server running Minecraft 1.8 or older without Gson included.

Solution: Use at least Minecraft 1.8.8 which includes the required Gson dependency, or manually add Gson to your classpath.

Expansions Won't Work After Reload

Cause: Internal expansion missing persist() = true override.

Solution: Add the following to your expansion class:

@Override
public boolean persist() {
    return true;
}

Best Practices

1. Always use provided/compileOnly scope - Never shade PlaceholderAPI into your plugin JAR
2. Prefer internal expansions - Better integration, no separate files to manage
3. Return null for invalid placeholders - Let PlaceholderAPI handle unknown identifiers
4. Use OfflinePlayer instead of Player - Works for offline players and avoids NPEs
5. Add soft dependency in plugin.yml - Ensures proper load order
6. Check if PAPI is enabled before registering: Bukkit.getPluginManager().isPluginEnabled("PlaceholderAPI")
7. Keep expansions lightweight - Focus on specific functionality, avoid heavy operations in onRequest()

Contributing

If you would like to contribute towards PlaceholderAPI, take a look at the Contributing file for the ins and outs on how you can do that and what you need to keep in mind.

Creating an Expansion

If you would like to create your own Placeholder Expansion for PlaceholderAPI, take a look at the Wiki which contains a detailed tutorial on how you can achieve this.

Support

• Issue Tracker: https://github.com/PlaceholderAPI/PlaceholderAPI/issues
• Discord Support: https://helpch.at/discord