PlaceholderAPI Integration

PrimeChat provides extensive integration with PlaceholderAPI, allowing dynamic content in chat formats, hover text, and messages throughout the plugin.

Overview

PlaceholderAPI integration in PrimeChat enables:

  • Dynamic Chat Formats: Player-specific information in chat

  • Rich Hover Text: Detailed player information on mouse-over

  • Personalized Messages: Custom content based on player data

  • Real-time Updates: Automatic refreshing of placeholder values

Installation Requirements

Required Plugins

  1. PlaceholderAPI - Core placeholder system

  2. Expansion Plugins - For specific placeholder types

Essential Expansions

# Install core expansions
/papi ecloud download Player
/papi ecloud download Vault
/papi ecloud download Server

# Apply expansions
/papi reload

Recommended Expansions

# Economy integration
/papi ecloud download Vault

# Permission system
/papi ecloud download LuckPerms

# Player statistics
/papi ecloud download Statistics

# Location information
/papi ecloud download Player

# Time-based placeholders
/papi ecloud download Server

Configuration Integration

Chat Format Placeholders

# In config.yml
chat:
  format: "&#E0E0E0[%vault_rank%&r&#E0E0E0] %player_name% &#888888»&#FDFDFD %message%"
  
  # Fallback format when PlaceholderAPI unavailable
  fallback-format: "<%player_name%> %message%"

Hover Information Placeholders

# In config.yml
chat:
  hover:
    enabled: true
    lines:
      - "&#00BFFF&lPlayer Information"
      - ""
      - "&#FFA500Player: &#FFFFFF%player_name%"
      - "&#FFA500Rank: &#FFFFFF%vault_rank%"
      - "&#FFA500Balance: &#FFFFFF%vault_eco_balance_formatted%"
      - "&#FFA500Health: &#FFFFFF%player_health%/%player_max_health%"
      - "&#FFA500Location: &#FFFFFF%player_world%"
      - "&#FFA500Playtime: &#FFFFFF%statistic_time_played%"

Private Message Placeholders

# In config.yml
private-messaging:
  sender-format: "&#FF69B4&o(To %receiver%)&r&#D3D3D3: %message%"
  receiver-format: "&#FF69B4&o(From %sender%)&r&#D3D3D3: %message%"

Available Placeholder Categories

Player Information

Basic Player Data

placeholders:
  "%player_name%": "Player's display name"
  "%player_uuid%": "Player's unique identifier"
  "%player_ping%": "Player's connection latency"
  "%player_locale%": "Player's client language"
  "%player_gamemode%": "Current game mode"

Player Health & Status

placeholders:
  "%player_health%": "Current health (hearts)"
  "%player_max_health%": "Maximum health"
  "%player_food_level%": "Hunger level (0-20)"
  "%player_level%": "Experience level"
  "%player_exp%": "Experience points"

Player Location

placeholders:
  "%player_world%": "Current world name"
  "%player_x%": "X coordinate"
  "%player_y%": "Y coordinate" 
  "%player_z%": "Z coordinate"
  "%player_biome%": "Current biome"

Vault Integration

Permission Groups

placeholders:
  "%vault_rank%": "Primary permission group"
  "%vault_rank_color%": "Group color code"
  "%vault_prefix%": "Group prefix"
  "%vault_suffix%": "Group suffix"

Economy System

placeholders:
  "%vault_eco_balance%": "Raw balance (123456.78)"
  "%vault_eco_balance_formatted%": "Formatted balance ($123,456.78)"
  "%vault_eco_balance_fixed%": "Fixed decimal balance (123456.78)"
  "%vault_eco_balance_commas%": "Comma separated (123,456)"

Server Information

Server Status

placeholders:
  "%server_name%": "Server name"
  "%server_online%": "Online player count"
  "%server_max_players%": "Maximum player slots"
  "%server_unique_joins%": "Total unique players"
  "%server_uptime%": "Server uptime"

Time & Date

placeholders:
  "%server_time%": "Current server time"
  "%server_time_24%": "24-hour format time"
  "%server_date%": "Current date"
  "%server_tps%": "Server TPS (ticks per second)"

Statistics Integration

Player Statistics

placeholders:
  "%statistic_time_played%": "Total playtime"
  "%statistic_deaths%": "Death count"
  "%statistic_mob_kills%": "Mob kills"
  "%statistic_player_kills%": "Player kills"
  "%statistic_jump%": "Jump count"
  "%statistic_blocks_broken%": "Blocks broken"
  "%statistic_blocks_placed%": "Blocks placed"

Advanced Usage Examples

Rank-Based Chat Formats

Admin Format

# For players with admin rank
chat:
  format: "&#FF0000&l[ADMIN] &#FFFFFF%player_name% &#FF0000&l❯ &#FFFFFF%message%"

VIP Format

# For VIP players
chat:
  format: "&#FFD700[&#FFFF00%vault_rank%&#FFD700] %player_name% &#888888❯ %message%"

Dynamic Format

# Format that adapts to any rank
chat:
  format: "%vault_prefix%%player_name%%vault_suffix% &#888888❯ &#FFFFFF%message%"

Rich Hover Information

Detailed Player Info

chat:
  hover:
    lines:
      - "&#00BFFF&l━━━ %player_name% ━━━"
      - ""
      - "&#FFA500◆ Rank: %vault_rank%"
      - "&#FFA500◆ Balance: %vault_eco_balance_formatted%"
      - "&#FFA500◆ Health: &#FF4500❤ %player_health%/20"
      - "&#FFA500◆ Level: &#32CD32⭐ %player_level%"
      - "&#FFA500◆ Playtime: %statistic_time_played%"
      - "&#FFA500◆ Location: %player_world% (%player_x%, %player_y%, %player_z%)"
      - ""
      - "&#87CEEB▶ Click to send a private message!"

Server Status Hover

chat:
  hover:
    lines:
      - "&#FFD700&l━━━ SERVER INFO ━━━"
      - ""
      - "&#32CD32◆ Online: %server_online%/%server_max_players%"
      - "&#32CD32◆ TPS: %server_tps%"
      - "&#32CD32◆ Uptime: %server_uptime%"
      - "&#32CD32◆ Time: %server_time%"

Conditional Formatting

Health-Based Colors

# Using conditional placeholders (requires additional plugins)
chat:
  format: "[%vault_rank%] %player_name% ❤%player_health_bar% ❯ %message%"

Economy-Based Prefixes

# Different prefixes based on balance
chat:
  format: "%vault_eco_tier_prefix%%player_name% ❯ %message%"

How Placeholders Work

Processing Order

  1. Plugin reads configuration with placeholder text

  2. PlaceholderAPI replaces placeholders with actual values

  3. Color codes are processed and applied

  4. Final formatted text is displayed to players

Where Placeholders Are Used

  • Chat Format: Player names, ranks, and custom data in chat

  • Hover Text: Detailed information when hovering over names

  • Messages: Dynamic content in plugin messages

  • Private Messages: Personalized formatting

Performance Optimization

Caching Configuration

# In config.yml (if implemented)
placeholderapi:
  cache:
    enabled: true
    duration: 30  # seconds
    
  refresh-interval: 60  # seconds
  
  fallbacks:
    "%vault_rank%": "Player"
    "%vault_eco_balance%": "0"

Efficient Placeholder Usage

Best Practices

  1. Limit Expensive Placeholders: Avoid database-heavy placeholders in frequently-used formats

  2. Use Caching: Enable placeholder caching where available

  3. Fallback Values: Provide defaults for when placeholders fail

  4. Async Processing: Process heavy placeholders off main thread

Performance-Optimized Format

# Efficient format using lightweight placeholders
chat:
  format: "[%vault_rank%] %player_name% ❯ %message%"
  
# Avoid expensive placeholders in main format
hover:
  lines:
    - "%player_name% - %vault_rank%"
    - "Balance: %vault_eco_balance_formatted%"
    - "Playtime: %statistic_time_played%"

Troubleshooting

Common Issues

Placeholders Showing as Text

# Issue: %placeholder% appears literally in chat
# Solutions:
1. Check PlaceholderAPI installation: /papi version
2. Install required expansions: /papi ecloud download Vault
3. Reload placeholders: /papi reload
4. Check plugin dependencies in console logs

Missing Placeholder Values

# Issue: Placeholders return empty or null values
# Solutions:
1. Verify expansion installation: /papi list
2. Test placeholders: /papi parse <player> %vault_rank%
3. Check dependent plugin installation (Vault, LuckPerms, etc.)
4. Review expansion documentation for correct usage

Performance Issues

# Issue: Server lag when processing placeholders
# Solutions:
1. Identify expensive placeholders: /timings report
2. Reduce placeholder frequency in formats
3. Enable placeholder caching where available
4. Use simpler alternatives for resource-intensive placeholders

Debug Commands

# Check PlaceholderAPI status
/papi version

# List installed expansions
/papi list

# Test specific placeholder
/papi parse <player> %placeholder%

# Reload all placeholders
/papi reload

# Download expansion
/papi ecloud download <expansion>

# Check expansion info
/papi ecloud info <expansion>

Custom Placeholders

PrimeChat may include custom placeholders in future versions for:

  • Chat game statistics

  • Player-specific data

  • Plugin-specific information

Check the plugin documentation or Discord for updates on custom placeholder availability.

Best Practices

Format Design

  1. Keep It Simple: Don't overcomplicate chat formats

  2. Performance First: Use lightweight placeholders for frequently-displayed content

  3. Fallback Planning: Always have fallback values for critical placeholders

  4. User Experience: Ensure formats are readable and not cluttered

  5. Testing: Test all placeholders before deploying to production

Maintenance

  1. Regular Updates: Keep PlaceholderAPI and expansions updated

  2. Monitor Performance: Watch for placeholder-related lag

  3. Document Dependencies: Track which expansions your formats require

  4. Backup Configurations: Save working configurations before making changes

  5. Community Feedback: Adjust formats based on player preferences

PreviousPermissionsNextColor & Formatting

Last updated