Prefixes

Supported software

Software	Support
Paper and forks	Full
Minestom	Planned
Fabric	Planned

Install the plugin

Install the server plugins

Download Prefixes from GitHub and place it in the Paper server template’s plugins/ folder. Standard SimpleCloud templates already include simplecloud-api; add it through the target’s Plugins setting or the CLI if you use a custom template.Install LuckPerms as well if you plan to use general.source: LUCKPERMS.

Generate the configuration

Start a matching server. Prefixes creates config.yml and messages.yml under plugins/simplecloud-prefixes/.

Keep the configuration in the template

For a group server, copy plugins/simplecloud-prefixes/ from the running server to the same path in its template before the server stops. Then edit the template copy.See Templates for the complete workflow.

Apply and verify the configuration

Run /scprefix reload after editing files on a running server. If you edited the template, start a new server instead.

Join the server and confirm that your group prefix appears in chat, the tab list, and your display name for each enabled feature.

Configuration

Every player belongs to a group whose settings define these displays. Prefixes reads groups from its own configuration or from LuckPerms.

config.yml

The main configuration file controls the group source, group definitions, individual features, and cross-server synchronization.

# The config format version. Do not change this value.
version: 1

# ─────────────────────────────────────────────────────────────────────────────
# General
# Controls how player groups are resolved.
# ─────────────────────────────────────────────────────────────────────────────
general:
  # Where groups are read from.
  # Available: CONFIG, LUCKPERMS
  source: CONFIG

  # Group used when a player matches no other group.
  # Must reference a group defined below when source is CONFIG.
  default-group: default

# ─────────────────────────────────────────────────────────────────────────────
# Features
# Each part of the plugin can be enabled independently.
# ─────────────────────────────────────────────────────────────────────────────
features:
  # Format chat messages using the group's chat-format.
  chat: true

  # Apply prefixes, suffixes, colors and sorting to the tab list.
  tablist: true

  # Apply the group's configured display-name.
  # When disabled, the player's normal Minecraft name is used.
  display-name: true

# ─────────────────────────────────────────────────────────────────────────────
# Sync
# Shares chat messages and tab list entries across the SimpleCloud network.
# Disabling sync does not disable local formatting.
# ─────────────────────────────────────────────────────────────────────────────
sync:
  # Master switch for all cross-server communication.
  enabled: true

  # Select which features are synchronized.
  # The corresponding feature above must also be enabled.
  channels:
    chat: true
    tablist: true

  # Groups and persistent servers from which updates are received.
  #
  # Special values:
  #   CURRENT - Current server group, or this persistent server.
  #   ALL     - Every server in the network. Must be used alone.
  #
  # Literal SimpleCloud group names and persistent server IDs can also be used.
  # Multiple sources can be combined, except when using ALL.
  sources:
  - CURRENT

# ─────────────────────────────────────────────────────────────────────────────
# Groups
# Only used when general.source is CONFIG.
#
# Supported placeholders:
#   <prefix>       Group prefix
#   <suffix>       Group suffix
#   <color>        Group color
#   <playername>   Normal Minecraft player name
#   <displayname>  Formatted display name
#   <message>      Chat message
# ─────────────────────────────────────────────────────────────────────────────
groups:
- name: owner
  # Higher priorities are selected first and sorted higher in the tab list.
  priority: 100
  # Permission required to use this group.
  permission: 'simplecloud.prefix.group.owner'
  prefix: '<#DC2626><bold>Owner</bold> <#475569>| '
  suffix: ''
  # Used by the <color> placeholder and player name coloring.
  color: '<#DC2626>'
  # Formatted player name.
  display-name: '<color><playername>'
  # Format used when features.chat is enabled.
  chat-format: '<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>'

- name: admin
  priority: 90
  permission: 'simplecloud.prefix.group.admin'
  prefix: '<#F59E0B><bold>Admin</bold> <#475569>| '
  suffix: ''
  color: '<#F59E0B>'
  display-name: '<color><playername>'
  chat-format: '<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>'

- name: default
  priority: 0
  # An empty permission matches every player.
  permission: ''
  prefix: '<#94A3B8>Player <#475569>| '
  suffix: ''
  color: '<#94A3B8>'
  display-name: '<color><playername>'
  chat-format: '<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>'

LuckPerms mapping When source is LUCKPERMS, every value is read from the LuckPerms group:

LuckPerms value	Prefixes value	Default if unset
Group name	`name`	Empty
Group weight	`priority`	`0`
Group prefix	`prefix`	empty
Group suffix	`suffix`	empty
Meta `color`	`color`	`#FFFFFF`
Meta `display-name`	`display-name`	`<color><playername>`
Meta `chat-format`	`chat-format`	`<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>`

/lp group admin setweight 90
/lp group admin meta addprefix 90 "<#F59E0B><bold>Admin</bold> <#475569>| "
/lp group admin meta set color "<#F59E0B>"
/lp group admin meta set display-name "<color><playername>"
/lp group admin meta set chat-format "<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>"

Placeholders

The following placeholders are available:

Placeholder	Available in	Description
`<prefix>`	`chat-format`	Prefix of the player’s group
`<suffix>`	`chat-format`	Suffix of the player’s group
`<color>`	`chat-format`, `display-name`	Team color of the player’s group, applied as styling
`<playername>`	`chat-format`, `display-name`	Plain player name
`<name>`	`chat-format`	Alias of `<playername>`
`<displayname>`	`chat-format`	Rendered display name of the player
`<message>`	`chat-format`	Chat message content

Use <color> instead of writing the same hex code into every value. It is applied as a style, so everything after it inherits the group color.

Feature switches

Use features to enable or disable each local part of the plugin:

chat formats local chat messages with the group’s chat-format
tablist applies the group’s prefix, suffix, color and priority to the tab list
display-name applies the configured display-name; when disabled, the normal Minecraft name is used

Cross-server sync

Sync can share two things over the SimpleCloud network:

Chat: formatted chat messages from players on other servers
Tab list: tab list entries for players on other servers

Set sync.enabled to false to disable all cross-server communication without disabling local formatting. Under channels, choose whether chat, tab list entries or both are synchronized. A channel only works when its matching option under features is also enabled. The sources list controls which servers this server receives updates from:

CURRENT receives updates from the current server group, or only this persistent server when running as a persistent server
ALL receives updates from every server in the network and must be the only list entry
A server group name or persistent server ID receives updates from that specific source

You can combine multiple group names and persistent server IDs. To exchange updates in both directions, configure each participating server to receive from the other server’s group or ID.

Commands

Command	Permission	Description
`/scprefix`	`simplecloud.prefixes.command`	Shows the command overview.
`/scprefix help`	`simplecloud.prefixes.command`	Shows the command overview.
`/scprefix reload`	`simplecloud.prefixes.command.reload`	Reloads the configuration.

API

Use the API to read a player’s prefix data and register custom groups.

Add the dependency

Access the API

Paper

import app.simplecloud.prefixes.api.PrefixesApi
import org.bukkit.Bukkit

val api = Bukkit.getServicesManager().getRegistration(PrefixesApi::class.java)?.provider
    ?: throw IllegalStateException("PrefixesApi is not registered")

import app.simplecloud.prefixes.api.PrefixesApi;
import org.bukkit.Bukkit;
import org.bukkit.plugin.RegisteredServiceProvider;

RegisteredServiceProvider<PrefixesApi> registration =
    Bukkit.getServicesManager().getRegistration(PrefixesApi.class);

if (registration == null) {
    throw new IllegalStateException("PrefixesApi is not registered");
}

PrefixesApi api = registration.getProvider();

The short examples below assume the api instance above and a platform player named player. Place them inside your plugin’s methods. The custom group example is a complete class.

Player management

Get the group of a player:

api.getPrimaryGroup(player.uniqueId).thenAccept { group ->
    player.sendMessage(Component.text("Your group: ${group?.name ?: "none"}"))
}

api.getPrimaryGroup(player.getUniqueId()).thenAccept(group -> {
    String name = group != null ? group.getName() : "none";

    player.sendMessage(Component.text("Your group: " + name));
});

Get the display values of a player:

api.getPrefixData(player.uniqueId).thenAccept { data ->
    player.sendMessage(data.prefix.append(data.displayName).append(data.suffix))
}

api.getPrefixData(player.getUniqueId()).thenAccept(data -> {
    player.sendMessage(data.getPrefix().append(data.getDisplayName()).append(data.getSuffix()));
});

Check whether a player is in a specific group:

val vip = api.getGroups().find { it.name == "vip" }

vip?.containsPlayerAsync(player.uniqueId)?.thenAccept { isVip ->
    if (isVip) {
        player.sendMessage(Component.text("Welcome back!"))
    }
}

PrefixesGroup vip = api.getGroups().stream()
    .filter(group -> group.getName().equals("vip"))
    .findFirst()
    .orElse(null);

if (vip == null) return;

vip.containsPlayerAsync(player.getUniqueId()).thenAccept(isVip -> {
    if (isVip) {
        player.sendMessage(Component.text("Welcome back!"));
    }
});

Group management

List all groups, highest priority first:

api.getGroups().forEach { group ->
    println("${group.priority} - ${group.name}")
}

api.getGroups().forEach(group ->
    System.out.println(group.getPriority() + " - " + group.getName()));

import app.simplecloud.prefixes.api.PrefixesApi
import app.simplecloud.prefixes.api.group.PrefixesGroup
import net.kyori.adventure.text.Component
import net.kyori.adventure.text.format.TextColor
import net.kyori.adventure.text.minimessage.MiniMessage
import java.util.UUID
import java.util.concurrent.CompletableFuture

class VipGroup(private val members: Set<UUID>) : PrefixesGroup {
    private val miniMessage = MiniMessage.miniMessage()

    override val name = "vip"
    override val priority = 50
    override val permission = "simplecloud.prefix.group.vip"
    override val prefix = miniMessage.deserialize("<#A3E635>VIP <#475569>| ")
    override val suffix = Component.empty()
    override val color = TextColor.fromHexString("#A3E635")
    override val displayName = "<color><playername>"
    override val chatFormat = "<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>"

    override fun containsPlayer(id: UUID) = id in members

    override fun containsPlayerAsync(id: UUID) =
        CompletableFuture.completedFuture(containsPlayer(id))
}

fun registerVipGroup(api: PrefixesApi, members: Set<UUID>): CompletableFuture<Void> =
    api.addGroup(VipGroup(members)).thenAccept { created ->
        if (!created) {
            println("A group named vip already exists")
        }
    }

import app.simplecloud.prefixes.api.PrefixesApi;
import app.simplecloud.prefixes.api.group.PrefixesGroup;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.TextColor;
import net.kyori.adventure.text.minimessage.MiniMessage;

import java.util.Set;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

public final class VipGroup implements PrefixesGroup {
    private final Set<UUID> members;

    public VipGroup(Set<UUID> members) {
        this.members = Set.copyOf(members);
    }

    @Override
    public String getName() {
        return "vip";
    }

    @Override
    public int getPriority() {
        return 50;
    }

    @Override
    public String getPermission() {
        return "simplecloud.prefix.group.vip";
    }

    @Override
    public Component getPrefix() {
        return MiniMessage.miniMessage().deserialize("<#A3E635>VIP <#475569>| ");
    }

    @Override
    public Component getSuffix() {
        return Component.empty();
    }

    @Override
    public TextColor getColor() {
        return TextColor.fromHexString("#A3E635");
    }

    @Override
    public String getDisplayName() {
        return "<color><playername>";
    }

    @Override
    public String getChatFormat() {
        return "<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>";
    }

    @Override
    public boolean containsPlayer(UUID id) {
        return members.contains(id);
    }

    @Override
    public CompletableFuture<Boolean> containsPlayerAsync(UUID id) {
        return CompletableFuture.completedFuture(containsPlayer(id));
    }

    public static CompletableFuture<Void> register(
        PrefixesApi api,
        Set<UUID> members
    ) {
        return api.addGroup(new VipGroup(members)).thenAccept(created -> {
            if (!created) {
                System.out.println("A group named vip already exists");
            }
        });
    }
}

Pass the member UUIDs when you register the group. If membership changes at runtime, replace the copied set with your plugin’s own thread-safe membership store.

Best practices

Keep priorities unique so the tab list order stays predictable
Give every group the same chat-format unless a rank should visibly stand out in chat
Use <color> in display-name and chat-format instead of repeating hex codes
Point default-group at a group with an empty permission so every player matches something

Introduction

Setup

Configuration

Plugins

Supported software

Install the plugin

Configuration

config.yml

Placeholders

Feature switches

Cross-server sync

Commands

API

Add the dependency

Access the API

Player management

Group management

Best practices

​Supported software

​Install the plugin

​Configuration

​config.yml

​Placeholders

​Feature switches

​Cross-server sync

​Commands

​API

​Add the dependency

​Access the API

​Player management

​Group management

​Best practices

Supported software

Install the plugin

Configuration

config.yml

Placeholders

Feature switches

Cross-server sync

Commands

API

Add the dependency

Access the API

Player management

Group management

Best practices