Placeholders

HyperPerms provides placeholders that can be used in chat plugins, scoreboards, and other plugins that support placeholder APIs.

Available Placeholders

PlaceholderAPI Integration

HyperPerms automatically integrates with PlaceholderAPI if it's installed. No additional configuration is required.

Using in Chat Plugins

Example with a chat plugin configuration:

# Example chat format config
chat:
  format: "%hyperperms_prefix%%player_name%%hyperperms_suffix%: %message%"

Using in Scoreboards

# Example scoreboard config
scoreboard:
  lines:
    - "&7Rank: &f%hyperperms_group_display%"
    - "&7Weight: &f%hyperperms_weight%"
    - "&7Groups: &f%hyperperms_groups_count%"

Using in Holograms

# Example hologram config
hologram:
  lines:
    - "%hyperperms_prefix%%player_name%"
    - "&7%hyperperms_group_display%"

Dynamic Placeholders

Permission Check Placeholder

Check if a player has a specific permission:

%hyperperms_has_fly.enable%
%hyperperms_has_mod.kick%
%hyperperms_has_admin.gamemode%

Info: Replace dots in permission nodes with underscores for the placeholder. For example, fly.enable becomes fly_enable.

Group Check Placeholder

Check if a player is in a specific group:

%hyperperms_in_group_vip%
%hyperperms_in_group_admin%
%hyperperms_in_group_moderator%

Track Placeholders

Get information about a player's position on tracks:

# Check if on a track
%hyperperms_on_track_staff%

# Get the player's group on a specific track
%hyperperms_track_staff_group%
%hyperperms_track_donor_group%

Usage Examples

VIP Status Display

# Show VIP status in tab list
tab:
  format: "%hyperperms_prefix%%player_name%"

# Conditional VIP indicator
sidebar:
  line: "VIP: %hyperperms_in_group_vip%"

Staff Rank Display

# Show staff rank on scoreboard
scoreboard:
  lines:
    - "&6Staff Rank"
    - "&f%hyperperms_track_staff_group%"
    - ""
    - "&6Your Groups"
    - "&f%hyperperms_groups%"

Permission-Based Content

# Show different content based on permissions
# (Requires a plugin that supports conditional placeholders)
fly_status: "%hyperperms_has_fly_enable%"
mod_tools: "%hyperperms_has_mod_kick%"

Programmatic Access

If you're developing a plugin and want to use HyperPerms placeholders:

import me.clip.placeholderapi.PlaceholderAPI;

public String formatMessage(Player player, String message) {
    // PlaceholderAPI will replace HyperPerms placeholders
    return PlaceholderAPI.setPlaceholders(player, message);
}

// Example usage
String formatted = formatMessage(player,
    "Welcome, %hyperperms_prefix%%player_name%!");

Custom Placeholder Expansion

You can create custom placeholders that use HyperPerms data:

import dev.hyperperms.api.HyperPermsProvider;
import me.clip.placeholderapi.expansion.PlaceholderExpansion;

public class MyExpansion extends PlaceholderExpansion {

    @Override
    public String onPlaceholderRequest(Player player, String params) {
        HyperPermsAPI api = HyperPermsProvider.get();
        User user = api.getUserManager().getUser(player.getUniqueId());

        if (params.equals("custom_rank")) {
            return user.getPrimaryGroup().getDisplayName();
        }

        return null;
    }

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

    @Override
    public String getAuthor() {
        return "Your Name";
    }

    @Override
    public String getVersion() {
        return "1.0.0";
    }
}

Performance Considerations

Tip: HyperPerms caches placeholder values to ensure good performance. The cache is automatically updated when permissions change.

• Placeholders are evaluated on demand
• Results are cached for efficiency
• Cache is invalidated when permissions change
• Avoid excessive placeholder usage in high-frequency updates

Troubleshooting

Placeholders Not Working

• Ensure PlaceholderAPI is installed
• Check that HyperPerms is loaded
• Verify placeholder syntax is correct
• Check for typos in permission/group names

Returning Empty/Wrong Values

• Player may not have joined before (no data)
• Group or permission might not exist
• Check with /hp user info <player>

See Also

• API Reference
• Color Codes
• Groups Guide