Placeholders

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

Available Placeholders

PlaceholderDescriptionExample Output
%hyperperms_group%Primary group nameadmin
%hyperperms_group_display%Primary group display nameAdministrator
%hyperperms_prefix%Player's prefix&c[Admin]
%hyperperms_suffix%Player's suffix&6*
%hyperperms_groups%All groups (comma-separated)admin, vip, default
%hyperperms_groups_count%Number of groups3
%hyperperms_weight%Highest group weight90
%hyperperms_has_<perm>%Check if has permissiontrue / false
%hyperperms_in_group_<group>%Check if in grouptrue / false
%hyperperms_on_track_<track>%Check if on tracktrue / false
%hyperperms_track_<track>_group%Group on specific trackmod

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:

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

Using in Scoreboards

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

Using in Holograms

yaml
# 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:

text
%hyperperms_has_fly.enable%
%hyperperms_has_mod.kick%
%hyperperms_has_admin.gamemode%
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:

text
%hyperperms_in_group_vip%
%hyperperms_in_group_admin%
%hyperperms_in_group_moderator%

Track Placeholders

Get information about a player's position on tracks:

text
# 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

yaml
# 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

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

Permission-Based Content

yaml
# 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:

java
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:

java
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

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