PlaceholderAPI Integration

Complete guide to using PlaceholderAPI placeholders in AnnouncementGUI announcements.

📋 Overview

AnnouncementGUI seamlessly integrates with PlaceholderAPI (PAPI), allowing you to create dynamic announcements with player-specific or server-specific information.

🎯 What is PlaceholderAPI?

PlaceholderAPI is a plugin that provides a unified system for displaying dynamic information from various plugins. It allows you to use placeholders like %player_name% or %vault_eco_balance% in your announcements.

📦 Installation

1

Install PlaceholderAPI

• Download PlaceholderAPI:

  • https://www.spigotmc.org/resources/placeholderapi.6245/

  • https://github.com/PlaceholderAPI/PlaceholderAPI/releases

• Install the plugin:

  • Place JAR in plugins/ folder

  • Restart server

• Verify installation:

/papi version

2

Install Expansions

PlaceholderAPI requires expansions for specific plugins.

• View available expansions:

/papi ecloud

• Install common expansions:

/papi ecloud download Player
/papi ecloud download Server
/papi ecloud download Vault
/papi ecloud download LuckPerms

• Reload PlaceholderAPI:

/papi reload

3

Verify AnnouncementGUI Integration

AnnouncementGUI automatically detects PlaceholderAPI.

• Check console on startup:

[AnnouncementGUI] PlaceholderAPI found! Placeholder support enabled.

🎨 Using Placeholders

Basic Syntax

Placeholders use this format:

%<identifier>_<value>%

Examples:

• %player_name% - Player's username

• %vault_eco_balance% - Player's economy balance

• %server_online% - Online player count

In Announcements

Simply include placeholders in your announcement messages.

Example 1: Welcome Message

<green>Welcome %player_name%!</green>
<yellow>You have $%vault_eco_balance%</yellow>

Example 2: Server Stats

<gold>Players Online: %server_online%</gold>
<aqua>Server TPS: %server_tps%</aqua>

Example 3: Player Info

<gray>Player: %player_displayname%</gray>
<gray>Rank: %luckperms_prefix%</gray>
<gray>World: %player_world%</gray>

📚 Common Placeholders

Player Placeholders

Basic Player Info

%player_name%              - Username (e.g., "Steve")
%player_displayname%       - Display name with formatting
%player_uuid%              - Player's UUID
%player_ping%              - Player's ping in ms
%player_world%             - Current world name
%player_x%                 - X coordinate (rounded)
%player_y%                 - Y coordinate (rounded)
%player_z%                 - Z coordinate (rounded)
%player_gamemode%          - Current gamemode
%player_health%            - Current health
%player_max_health%        - Maximum health
%player_food_level%        - Food level (0-20)
%player_level%             - Experience level
%player_total_exp%         - Total experience points

Example Usage:

<green>Hello %player_displayname%!</green>
<gray>Ping: %player_ping%ms | World: %player_world%</gray>

Server Placeholders

Server Statistics

%server_name%              - Server name from server.properties
%server_online%            - Online player count
%server_max_players%       - Maximum players
%server_tps%               - Server TPS (requires expansion)
%server_ram_used%          - Used RAM
%server_ram_free%          - Free RAM
%server_ram_max%           - Maximum RAM

Example Usage:

<gold>Server: %server_name%</gold>
<yellow>Players: %server_online%/%server_max_players%</yellow>
<green>TPS: %server_tps%</green>

Economy Placeholders (Vault)

Requires:

• Vault plugin

• Economy plugin (e.g., EssentialsX, CMI)

• Vault expansion: /papi ecloud download Vault

%vault_eco_balance%                    - Player's balance
%vault_eco_balance_formatted%          - Formatted balance
%vault_eco_balance_fixed%              - Balance with 2 decimals
%vault_eco_balance_commas%             - Balance with commas

Example Usage:

<gold>Balance: $%vault_eco_balance_formatted%</gold>
<yellow>Vote and earn money!</yellow>

Permission Placeholders (LuckPerms)

Requires:

• LuckPerms plugin

• LuckPerms expansion: /papi ecloud download LuckPerms

%luckperms_prefix%                 - Player's prefix
%luckperms_suffix%                 - Player's suffix
%luckperms_primary_group%          - Primary group name
%luckperms_highest_group%          - Highest weighted group
%luckperms_has_permission_<permission>% - Check permission (true/false)

Example Usage:

%luckperms_prefix% %player_name%: <gray>Welcome!</gray>
<yellow>Your rank: %luckperms_primary_group%</yellow>

Statistics Placeholders

Requires: Statistics expansion

%statistic_deaths%                 - Total deaths
%statistic_mob_kills%              - Total mob kills
%statistic_player_kills%           - Total player kills
%statistic_time_played%            - Total time played (ticks)
%statistic_<stat>%                 - Any Minecraft statistic

Time Placeholders

Requires: Server expansion

%server_time%                      - Current time (HH:mm:ss)
%server_time_HH%                   - Hour (24h format)
%server_time_mm%                   - Minute
%server_time_ss%                   - Second

🔧 Creating Dynamic Announcements

Example 1: Personalized Welcome

Goal: Welcome players with their name and balance.

Configuration:

Name: Personalized Welcome
Message:
  <green>Welcome back, %player_name%!</green>
  <yellow>Balance: $%vault_eco_balance%</yellow>
  <gray>Online players: %server_online%</gray>
Interval: 300
Server: ALL

Result:

Welcome back, Steve!
Balance: $1,234.56
Online players: 42

Example 2: Rank-Based Messages

Goal: Show player's rank in announcements.

Configuration:

Name: Rank Display
Message:
  <gold>Your rank: %luckperms_prefix%%player_name%</gold>
  <yellow>Enjoying your %luckperms_primary_group% perks?</yellow>
Interval: 600
Server: ALL

Result (for VIP):

Your rank: [VIP] Steve
Enjoying your VIP perks?

Example 3: Server Status

Goal: Display current server statistics.

Configuration:

Name: Server Stats
Message:
  <aqua>━━━ Server Information ━━━</aqua>
  <yellow>Players: %server_online%/%server_max_players%</yellow>
  <yellow>TPS: %server_tps%</yellow>
  <yellow>RAM: %server_ram_used%MB / %server_ram_max%MB</yellow>
Interval: 300
Server: ALL

Example 4: Time-Based Greeting

Goal: Different greeting based on time.

Configuration:

Name: Time-Based Greeting
Message:
  <gold>Good %server_time_HH < 12 ? "morning":"afternoon"%, %player_name%!</gold>
  <gray>Current time: %server_time%</gray>
Interval: 600
Server: ALL

Example 5: Achievement Encouragement

Goal: Show player progress.

Configuration:

Name: Player Progress
Message:
  <green>%player_name%, you've played for %statistic_time_played% ticks!</green>
  <yellow>Kills: %statistic_mob_kills% | Deaths: %statistic_deaths%</yellow>
  <gray>Keep up the great work!</gray>
Interval: 900
Server: survival

⚡ Performance Considerations

Per-Player vs Broadcast Mode

AnnouncementGUI automatically detects placeholders and adjusts.

Broadcast Mode (No Placeholders):

<green>Welcome to our server!</green>
<yellow>Type /help for commands</yellow>

• Performance: Fast - one message for all players

• Usage: Static announcements

Per-Player Mode (With Placeholders):

<green>Welcome %player_name%!</green>
<yellow>Balance: $%vault_eco_balance%</yellow>

• Performance: Slower - message parsed per player

• Usage: Dynamic, personalized announcements

Optimization Tips

1. Use sparingly: Don't use placeholders in every announcement

2. Batch placeholders: Put all placeholders in one announcement

3. Cache-friendly: Use server placeholders (cached) over player-specific ones

4. Longer intervals: Use longer intervals for placeholder announcements

Example - Optimized:

Announcement 1 (Every 2 minutes):
- Message: Static welcome message
- No placeholders
- Fast broadcast

Announcement 2 (Every 10 minutes):
- Message: Player stats with placeholders
- Placeholders: %player_name%, %vault_eco_balance%
- Per-player parsing

🔍 Testing Placeholders

In-Game Testing

Test command:

/papi parse me <placeholder>

Examples:

/papi parse me %player_name%
/papi parse me %vault_eco_balance%
/papi parse me %server_online%

Common Placeholder Issues

Placeholder shows as-is

Example: Message shows %player_name% instead of "Steve"

Causes:

• PlaceholderAPI not installed

• Required expansion not installed

• Syntax error in placeholder

Solutions:

# Check PlaceholderAPI
/papi version

# List installed expansions
/papi list

# Test placeholder
/papi parse me %player_name%

# Install missing expansion
/papi ecloud download <expansion>
/papi reload

Placeholder returns "Invalid placeholder"

Causes:

• Expansion not installed

• Incorrect placeholder syntax

• Required plugin not installed

Solutions:

1. Install required expansion

2. Check placeholder spelling

3. Verify required plugin is installed

Placeholder works in chat but not announcements

Causes:

• AnnouncementGUI not detecting PlaceholderAPI

• Plugin load order issue

Solutions:

1. Check AnnouncementGUI console output

2. Verify PlaceholderAPI in server.properties softdepend or depend

3. Restart server (not reload)

📚 Expansion Library

Essential Expansions

Expansion	Plugin Required	Common Use
Player	None	Player info (%player_name%, etc.)
Server	None	Server stats (%server_online%, etc.)
Vault	Vault + Economy	Economy balance, groups
LuckPerms	LuckPerms	Permissions, ranks
Statistics	None	Player statistics

Popular Expansions

Expansion	Plugin Required	Placeholders
EssentialsX	EssentialsX	Homes, warps, balance
CMI	CMI	Various CMI features
Factions	Factions	Faction info
mcMMO	mcMMO	Skill levels
Jobs	Jobs	Job levels, balance
Towny	Towny	Town info
WorldGuard	WorldGuard	Region info
Marriage	Marriage	Partner info
Clans	Clans	Clan info

Installing Expansions

Method 1: In-Game (Recommended)

/papi ecloud download <expansion>
/papi reload

Method 2: Manual Download

1. Visit https://api.extendedclip.com/expansions/

2. Download expansion JAR

3. Place in plugins/PlaceholderAPI/expansions/

4. /papi reload

🎨 Advanced Techniques

Conditional Placeholders

Some expansions support conditional logic.

Example with Parse expansion:

%parseother_{player}_player_name%  - Other player's name

Mathematical Operations

Example with Math expansion:

%math_{%vault_eco_balance%+1000}%  - Balance + 1000

Relational Placeholders

Show info about two players:

%rel_<placeholder>%  - Relational placeholder

JavaScript Placeholders

Example with JavaScript expansion:

%javascript_<code>%

🔧 Troubleshooting

Debug Mode

Enable debug mode in PlaceholderAPI config:

config.yml:

debug: true

Then check console for placeholder parsing details.

Common Problems

Lag with placeholders

Solutions:

1. Increase announcement interval

2. Reduce number of placeholders

3. Use cached placeholders (server stats)

4. Update PlaceholderAPI and expansions

Outdated placeholder values

Solutions:

1. Update expansion: /papi ecloud download <expansion>

2. Reload PlaceholderAPI: /papi reload

3. Check expansion update interval in config

Placeholder from plugin not working

Solutions:

1. Verify plugin is running: /plugins

2. Install correct expansion: /papi ecloud download <plugin>

3. Check expansion compatibility with plugin version

4. Restart server (don't just reload)

📖 Best Practices

1. Test Before Deploying

Always test placeholders:

/papi parse me <your_announcement_text>

1. Use Descriptive Names

✅ Good: "Player Welcome - PAPI"
❌ Bad: "Announcement 1"

1. Balance Performance

• Mix static and dynamic announcements

• Don't overuse placeholders

• Use appropriate intervals

1. Keep Expansions Updated

/papi ecloud refresh
/papi ecloud update <expansion>

1. Document Dependencies

Keep a list of required expansions:

Required Expansions:
- Player (for %player_name%)
- Server (for %server_online%)
- Vault (for %vault_eco_balance%)

1. Fallback Values

Some placeholders return empty when unavailable. Plan for this:

✅ Good: <green>Balance: $%vault_eco_balance%</green>
Better: <green>Balance: ${%vault_eco_balance%|0}</green> (with fallback)

📝 Example Announcement Pack

1

Welcome Message (Static)

Name: Welcome - Static

Message:
  <gradient:green:aqua>Welcome to Our Server!</gradient>
  <yellow>Type /help for commands</yellow>
Interval: 300
Server: ALL

2

Player Stats (Dynamic)

Name: Player Stats - PAPI

Message:
  <green>Hello %player_name%!</green>
  <yellow>Balance: $%vault_eco_balance_formatted%</yellow>
  <gray>Rank: %luckperms_primary_group%</gray>
Interval: 600
Server: ALL

3

Server Info (Semi-Dynamic)

Name: Server Info - PAPI

Message:
  <aqua>━━━ Server Status ━━━</aqua>
  <yellow>Players: %server_online%/%server_max_players%</yellow>
  <yellow>TPS: %server_tps%</yellow>
Interval: 300
Server: ALL

4

Vote Reminder (Mixed)

Name: Vote Reminder - PAPI

Message:
  <gold>%player_name%, vote for rewards!</gold>
  <yellow>Current balance: $%vault_eco_balance%</yellow>
  <gray>Vote at: /vote</gray>
Interval: 900
Server: ALL

🔗 Resources

Official Links

• PlaceholderAPI: https://github.com/PlaceholderAPI/PlaceholderAPI

• Wiki: https://wiki.placeholderapi.com/

• eCloud: https://api.extendedclip.com/expansions/

• Discord: https://helpch.at/discord

Commands Reference

/papi                          - Main command
/papi info <expansion>         - Expansion info
/papi list                     - List installed expansions
/papi ecloud                   - Browse available expansions
/papi ecloud download <exp>    - Download expansion
/papi reload                   - Reload PlaceholderAPI
/papi parse me <text>          - Test placeholder parsing

---