LuckPerms Integration

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