> ## Documentation Index
> Fetch the complete documentation index at: https://new-docs.simplecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Prefixes

> Learn about SimpleCloud's prefixes plugin for managing player ranks in chat and tab list

## Overview

The Prefixes Plugin manages player ranks in chat and tab list displays. It integrates with LuckPerms by default but can be extended with custom implementations. The plugin uses Adventure Components and MiniMessage for text formatting.

## Supported Software

| Server Type   | API Support | LuckPerms | Plugin Support |
| ------------- | ----------- | --------- | -------------- |
| Paper & Forks | ✅ Yes       | ✅ Yes     | ✅ Yes          |
| Minestom      | ✅ Yes       | ❌ No      | ❌ No           |

<Note>
  Minestom support requires custom implementation using the provided API.
</Note>

## Quick Setup

1. Download custom names from [GitHub](https://github.com/spacechunks/custom-names)
2. Download the plugin from [GitHub](https://github.com/simplecloudapp/prefixes-plugin/releases)
3. Place it in your server's plugins folder
4. Start your server
5. Configure using LuckPerms and `config.json`

## Configuration

### LuckPerms Integration

The plugin automatically syncs with LuckPerms groups, converting them to prefix groups with their respective prefixes, suffixes, and team colors.

```bash theme={null}
# Set group prefix
/lp group admin meta addprefix 100 "<red>[Admin] "

# Set group suffix
/lp group admin meta addsuffix 100 " <gray>✦"

# Set team color
/lp group admin meta set color #FF0000
```

### Chat Configuration

Configure chat format in `config.json`:

```json theme={null}
{
  "chatFormat": "<prefix><name_colored><suffix><gray>:</gray> <white><message></white>"
}
```

Available placeholders:

| Placeholder    | Description          |
| -------------- | -------------------- |
| `name`         | Player's name        |
| `name_colored` | Name with team color |
| `prefix`       | Player's prefix      |
| `suffix`       | Player's suffix      |
| `message`      | Chat message         |

## API Usage

### Accessing the API

<Tabs>
  <Tab title="Bukkit/Paper">
    ```kotlin theme={null}
    val prefixesApiProvider = Bukkit.getServicesManager()
        .getRegistration(PrefixesApi::class.java)
    val api: PrefixesApi = prefixesApiProvider.provider

    // Use API
    api.setPrefix(player.uniqueId, Component.text("[VIP] "))
    ```
  </Tab>

  <Tab title="Minestom">
    ```kotlin theme={null}
    val api: PrefixesApi = PrefixesExtension.getApi()

    // Use API
    api.setPrefix(player.uniqueId, Component.text("[VIP] "))
    ```
  </Tab>
</Tabs>

### Core API Methods

```kotlin theme={null}
// Player Management
fun setWholeName(uniqueId: UUID, group: PrefixesGroup)
fun setPrefix(uniqueId: UUID, prefix: Component)
fun setSuffix(uniqueId: UUID, suffix: Component)
fun setColor(uniqueId: UUID, color: String)

// Group Management
fun getGroups(): List<PrefixesGroup>
fun getHighestGroup(uniqueId: UUID): PrefixesGroup
fun addGroup(group: PrefixesGroup)
```

## Custom Implementation

### Creating a Custom Group

```kotlin theme={null}
class CustomGroup : PrefixesGroup {
    override fun getName(): String = "vip"
    override fun getPrefix(): Component = Component.text("[VIP] ")
    override fun getSuffix(): Component = Component.text(" ⭐")
    override fun getColor(): String = "#FFD700"
    override fun getPriority(): Int = 100

    override fun containsPlayer(uniqueId: UUID): Boolean {
        // Custom logic
        return true
    }
}
```

### Custom Actor Implementation

```kotlin theme={null}
class CustomActor : PrefixesActor {
    override fun applyGroup(target: UUID, group: PrefixesGroup) {
        // Apply group formatting
    }

    override fun setPrefix(target: UUID, prefix: Component) {
        // Set player prefix
    }

    override fun formatMessage(target: UUID, format: String, message: Component): Component {
        // Format chat message
        return Component.text()
            .append(prefix)
            .append(message)
            .build()
    }
}
```

<Note>
  For complete implementation examples, check our [GitHub
  repository](https://github.com/simplecloudapp/prefixes-plugin).
</Note>

## Best Practices

1. **Group Management**
   * Use consistent prefix/suffix styles
   * Set appropriate group priorities
   * Document group hierarchies

2. **Performance**
   * Cache group data when possible
   * Use async operations for database queries
   * Minimize chat format complexity