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. 1.21.4-R0.1-SNAPSHOT

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%