# LuckPerms Integration

# LuckPerms Integration

The Achievement plugin integrates with [LuckPerms](https://luckperms.net/) 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](https://luckperms.net/download) 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

```bash
# 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:

```yaml
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:

```bash
/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:

```json
"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`:
```json
"display": {
  "titlePosition": "prefix"  // "prefix", "above", "below"
}
```

## Troubleshooting

### Prefix Not Showing

1. Check LuckPerms is installed:
   ```bash
   /lp info
   ```

2. Verify prefix is set:
   ```bash
   /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:
   ```bash
   /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