EssentialsC / Scoreboard Placeholders

Scoreboard Placeholders

Complete reference for built-in placeholders and PlaceholderAPI integration for the scoreboard system.

Overview

EssentialsC's scoreboard supports two types of placeholders:

  • Built-in placeholders - Always available, no external plugins required. These are processed by EssentialsC directly.
  • PlaceholderAPI placeholders - Requires PlaceholderAPI to be installed. Provides access to hundreds of placeholders from various plugins.
When PlaceholderAPI is not installed, EssentialsC automatically falls back to built-in placeholders. You can check which mode is active by running /scoreboard status.

Built-in Placeholders

These placeholders work without any external plugins. Use them in your scoreboard title and lines configuration.

Player Placeholders

Placeholder Description Example Output
%player_name% The player's username. Notch
%player_displayname% The player's display name (may include formatting). Notch
%player_ping% The player's current ping in milliseconds. 42
%ping% Alias for %player_ping%. 42
%level% The player's experience level. 34
%world% The world the player is currently in. world
%x% The player's X coordinate (block). 128
%y% The player's Y coordinate (block). 64
%z% The player's Z coordinate (block). -256

Statistic Placeholders

Placeholder Description Example Output
%statistic_player_kills% Total number of player kills. 142
%statistic_deaths% Total number of deaths. 23

Server Placeholders

Placeholder Description Example Output
%server_online% Number of players currently online. 12
%server_max_players% Maximum player slots on the server. 50
%server_tps_1% Server TPS (1-minute average), formatted to 1 decimal. 19.8
%server_tps_5% Server TPS (5-minute average), formatted to 1 decimal. 19.9
%server_tps_15% Server TPS (15-minute average), formatted to 1 decimal. 20.0
%server_version% The server's Bukkit version string, with build suffixes stripped. 1.21.4

Integration Placeholders (Direct API)

When the corresponding plugin is installed, EssentialsC reads data directly from the plugin's API. These work without PlaceholderAPI.

Placeholder Requires Description
%luckperms_prefix% LuckPerms The player's LuckPerms meta prefix (e.g. their rank tag).
%luckperms_suffix% LuckPerms The player's LuckPerms meta suffix.
%vault_eco_balance% Vault The player's raw economy balance.
%vault_eco_balance_formatted% Vault The player's balance formatted by Vault (e.g. $1,234.56).
If LuckPerms or Vault are not installed, these placeholders are replaced with an empty string.

PlaceholderAPI Support

When PlaceholderAPI is installed, EssentialsC automatically expands all %placeholder% tokens through PlaceholderAPI's setPlaceholders() method before applying built-in replacements.

This gives you access to hundreds of placeholders from PlaceholderAPI expansion plugins, including:

  • Player - %player_name%, %player_health%, %player_gamemode%
  • Server - %server_uptime%, %server_memory%
  • Vault - %vault_eco_balance%, %vault_perm_group%
  • LuckPerms - %luckperms_prefix%, %luckperms_suffix%, %luckperms_primary_group_name%
  • And many more...
PlaceholderAPI placeholders are processed first, then built-in placeholders are applied. This means if a PlaceholderAPI expansion provides %player_name%, it will be replaced by PlaceholderAPI, and EssentialsC's built-in replacement will have no effect (since the %...% token is already gone).

Checking Status

Run /scoreboard status to check whether PlaceholderAPI is detected:

  • "PlaceholderAPI detected" - External placeholders are enabled. Your config placeholders will work as expected.
  • "PlaceholderAPI not detected" - Built-in placeholders only. Some placeholders in your config may not resolve. Install PlaceholderAPI for full support.

Examples

Basic Scoreboard (Built-in Only)

config.yml 
scoreboard:
  enabled: true
  title: "<#279FF5><b>My Server"
  lines:
    - ""
    - "<#279FF5><b>%player_name%:"
    - "<#279FF5><b>| <#9CD6FF>Rank: <white>%luckperms_prefix%"
    - "<#279FF5><b>| <#9CD6FF>Balance: <white>%vault_eco_balance_formatted%"
    - "<#279FF5><b>| <#9CD6FF>Kills: <white>%statistic_player_kills%"
    - "<#279FF5><b>| <#9CD6FF>Deaths: <white>%statistic_deaths%"
    - "<#279FF5><b>| <#9CD6FF>Ping: <white>%player_ping%<#9CD6FF>ms"
    - ""
    - "<#279FF5><b>| <#9CD6FF>Online: <white>%server_online%<gray>/<white>%server_max_players%"
    - "<#279FF5><b>| <#9CD6FF>TPS: <white>%server_tps_1%"

Scoreboard with PlaceholderAPI

config.yml (with PlaceholderAPI installed) 
scoreboard:
  enabled: true
  title: "<gold><b>%luckperms_primary_group_name%"
  lines:
    - "<gray>Health: <white>%player_health%<gray>/<white>%player_health_max%"
    - "<gray>World: <white>%world%"
    - "<gray>Time: <white>%essentials_time%"
    - "<gray>Balance: <white>%vault_eco_balance%"

Troubleshooting

Placeholders show as raw text (%placeholder_name%)

If placeholders appear literally in your scoreboard (e.g. %luckperms_prefix% instead of the actual prefix), check the following:

Issue Solution
PlaceholderAPI not installed Install PlaceholderAPI, or use built-in placeholders that don't require it.
Required expansion not installed Run /papi ecloud download <expansion> to install the needed expansion.
Placeholder is not a valid placeholder Check the placeholder syntax. Must be %placeholder_name% with no typos.
Plugin providing the placeholder is not installed Ensure the plugin that provides this placeholder is installed and enabled.

Checking Placeholder Status

Use the /scoreboard status command to see whether PlaceholderAPI is detected and whether built-in placeholders are being used.

You can test individual placeholders using PlaceholderAPI's /papi parse command: /papi parse me %luckperms_prefix%