Skip to main content

LuckPerms Integration

The Achievement plugin integrates with LuckPerms for automatic prefix retrieval and rich color formatting.

Overview​

When LuckPerms is installed, the plugin:

  1. Automatically detects LuckPerms at runtime
  2. Retrieves player prefixes from LuckPerms groups
  3. Supports all LuckPerms color formats
  4. Combines prefixes with achievement titles in chat

Installation​

  1. Install LuckPerms on your server
  2. The Achievement plugin automatically detects it
  3. No additional configuration required

Check server logs for confirmation:

[KyuubiSoft Achievements] LuckPerms integration enabled

Chat Format​

With LuckPerms integration, chat messages display as:

[LuckPerms Prefix] [Achievement Title] Username: Message

Example:

[Admin] [Spider Slayer] Steve: Hello everyone!

Color Support​

The plugin supports all LuckPerms color formats:

MiniMessage Tags​

<red>Text</red>
<gold>Text</gold>
<#FF5555>Hex Color</#FF5555>

Gradients​

<gradient:#FF0000:#00FF00>Rainbow Text</gradient>

Rainbow​

<rainbow>Colorful Text</rainbow>

Legacy Codes​

&a Green
&b Aqua
&c Red
&6 Gold

Prefix Configuration in LuckPerms​

Via Commands​

# Set prefix for a group
/lp group admin meta setprefix 100 "<red>[Admin]</red> "

# Set prefix for a user
/lp user Steve meta setprefix 100 "<gold>[VIP]</gold> "

Via Config​

In your LuckPerms group file:

admin:
  permissions:
    - "meta.prefix.100.<red>[Admin]</red> "

Priority System​

When multiple prefixes are available:

  1. User-specific prefix (highest priority)
  2. Primary group prefix
  3. Inherited group prefixes (by weight)
  4. Config fallback (groupPrefixes in config.json)

Trailing Styles​

The plugin extracts "trailing styles" from prefixes:

Example prefix:

<bold><#2b2b2b>[<gradient:#ff85fb:#85fbff>Mythic</gradient><#2b2b2b>] <#be8fff>

Extracted trailing style:

  • Color: #be8fff (purple)
  • Bold: true

Applied to username:

  • Username appears in purple and bold
  • Matches the prefix style

Suffix Support​

LuckPerms suffixes are also supported:

/lp group vip meta setsuffix 100 " <gray>⭐</gray>"

Chat output:

[VIP] [Title] Steve ⭐: Hello!

Suffix trailing color applies to the message text.

Configuration Fallback​

If LuckPerms is not installed or a group has no prefix, use the config fallback:

"groupPrefixes": {
  "admin": {
    "prefix": "<red>[Admin]</red> ",
    "priority": 100
  },
  "moderator": {
    "prefix": "<blue>[Mod]</blue> ",
    "priority": 75
  },
  "vip": {
    "prefix": "<gold>[VIP]</gold> ",
    "priority": 50
  },
  "default": {
    "prefix": "",
    "priority": 0
  }
}

Lazy Initialization​

The plugin uses lazy initialization for LuckPerms:

  1. Plugin loads before or after LuckPerms (order doesn't matter)
  2. LuckPerms API is initialized on first use (first chat message)
  3. Works with --accept-early-plugins flag

This ensures compatibility regardless of plugin load order.

Nametag Display​

Titles appear on player nametags:

Prefix Position (default)​

[Title] PlayerName

Above Position​

    [Title]
  PlayerName

Below Position​

  PlayerName
    [Title]

Configure in config.json:

"display": {
  "titlePosition": "prefix"  // "prefix", "above", "below"
}

Troubleshooting​

Prefix Not Showing​

  1. Check LuckPerms is installed:

    /lp info

  2. Verify prefix is set:

    /lp user Steve info

  3. Check server logs for errors

Colors Not Working​

  1. Ensure correct MiniMessage syntax
  2. Check for unclosed tags
  3. Test with simple colors first: 
    /lp group admin meta setprefix 100 "<red>[Admin]</red> "

Load Order Issues​

If you see:

LuckPerms found but not yet loaded

This is normal - the plugin uses lazy initialization and will work correctly.

Technical Details​

API Access​

The plugin accesses LuckPerms via:

  1. LuckPermsProvider.get() - Main API
  2. userManager.getUser() - Get user data
  3. user.getCachedData() - Get cached metadata
  4. metaData.getPrefix() - Get prefix string

Fallback Chain​

User Cached Metadata (contextual)
        ↓ (if null)
User Cached Metadata (non-contextual)
        ↓ (if null)
Primary Group Cached Metadata
        ↓ (if null)
Direct Group Node Parsing (meta.prefix.*)
        ↓ (if null)
Config groupPrefixes Fallback

Color Conversion​

LuckPerms prefixes (MiniMessage format) are converted to Hytale Message format:

MiniMessage: <red>[Admin]</red>
     ↓
Adventure Component: TextComponent(color=RED, text="[Admin]")
     ↓
Hytale Message: Message.raw("[Admin]").color("#FF5555")

This conversion preserves:

  • Colors (named, hex, gradients)
  • Bold, italic, underline, strikethrough
  • Nested styles