Prefixes

Supported software

Software	Support
Paper and forks	Full, including Folia
Minestom	Full, as a library
Fabric	Planned

Prefixes works with or without SimpleCloud. Only cross-server sync needs a SimpleCloud network.

Install the plugin

Paper
Minestom

Install the plugin

Download Prefixes from GitHub or Modrinth and place it in the server template’s plugins/ folder.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 above your head for each enabled feature.

On Minestom, Prefixes is a library that you bundle with your server and start from your code.

Add the dependency

Start Prefixes

Start Prefixes after MinecraftServer.init().

import app.simplecloud.prefixes.minestom.PrefixesMinestom
import net.minestom.server.MinecraftServer
import java.nio.file.Path

fun main() {
    val server = MinecraftServer.init()

    val prefixes = PrefixesMinestom.builder(Path.of("prefixes"))
        .permission { player, _ -> player.permissionLevel >= 4 }
        .enable()

    MinecraftServer.getSchedulerManager().buildShutdownTask { prefixes.shutdown() }
    server.start("0.0.0.0", 25565)
}

import app.simplecloud.prefixes.minestom.PrefixesMinestom;
import net.minestom.server.MinecraftServer;

import java.nio.file.Path;

public final class Server {
    public static void main(String[] args) {
        MinecraftServer server = MinecraftServer.init();

        PrefixesMinestom prefixes = PrefixesMinestom.builder(Path.of("prefixes"))
            .permission((player, permission) -> player.getPermissionLevel() >= 4)
            .enable();

        MinecraftServer.getSchedulerManager().buildShutdownTask(prefixes::shutdown);
        server.start("0.0.0.0", 25565);
    }
}

Replace the permission check with your own permission system. The builder supports these options:

Option	Default	Description
`permission(check)`	None	Decides which config group a player gets and who may use `/scprefix`.
`registerCommands(bool)`	`true`	Registers the `/scprefix` command.
`luckPerms(instance)`	`LuckPermsProvider.get()`	Sets the LuckPerms instance when it is not available through the LuckPerms provider.

Verify the setup

Start the server and join it. Your group prefix appears in chat, the tab list, and above your head.

Configuration

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

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 loaded from.
  # Available: config, luckperms, or the name of a custom provider.
  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

  # Show the prefix, the colored player name and the suffix in the tab list,
  # sorted by group priority.
  tablist: true

  # Show the group's display-name above the player's head.
  # When disabled, the normal Minecraft name tag is shown instead.
  display-name: true

# ─────────────────────────────────────────────────────────────────────────────
# Sync
# Shares chat messages and tab list entries across the SimpleCloud network.
# ─────────────────────────────────────────────────────────────────────────────
sync:
  # Master switch for all cross-server communication.
  enabled: false

  # 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.
#
# Placeholders in display-name:
#   <prefix>       Group prefix
#   <suffix>       Group suffix
#   <color>        Group color
#   <playername>   Normal Minecraft player name
#
# Placeholders in chat-format:
#   <prefix>       Group prefix
#   <suffix>       Group suffix
#   <color>        Group color
#   <playername>   Normal Minecraft player name (alias: <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>'
  # Name shown above the player's head, e.g. '<prefix><color><playername>'.
  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>'

Group sources

general.source selects where groups come from.

Source	Description
`config`	Uses the groups defined under `groups`.
`luckperms`	Uses LuckPerms groups. Requires LuckPerms on the server.
Custom name	Uses a group provider that another plugin registers through the API.

LuckPerms mapping When source is luckperms, every value is read from the LuckPerms group. Prefixes picks the player’s group with the highest weight among their primary and inherited groups.

LuckPerms value	Prefixes value	Default if unset
Group name	`name`	—
Group weight	`priority`	`0`
Group prefix	`prefix`	Empty
Group suffix	`suffix`	Empty
Meta `color`	`color`	White
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 "<prefix><color><playername>"
/lp group admin meta set chat-format "<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>"

Prefixes updates players automatically when their LuckPerms groups or group data change.

Placeholders

The following placeholders are available:

Placeholder	Available in	Description
`<prefix>`	`chat-format`, `display-name`	Prefix of the player’s group
`<suffix>`	`chat-format`, `display-name`	Suffix of the player’s group
`<color>`	`chat-format`, `display-name`	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 shows the prefix, the player name in the group color, and the suffix in the tab list, sorted by priority
display-name shows the group’s display-name above the player’s head; when disabled, the normal Minecraft name tag is shown

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

Sync is disabled by default. Set sync.enabled to true to turn it on. 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.

Enabling sync or changing sync.sources only takes effect after a server restart.

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 `config.yml` and `messages.yml`.

API

Use the API to read and change how players are shown, and to add your own groups.

Add the dependency

Access the API

Paper
Minestom

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();

val api = PrefixesMinestom.getApi()

PrefixesApi api = PrefixesMinestom.getApi();

On every platform, you can also use PrefixesApiProvider.get(), which throws an IllegalStateException if Prefixes is not running.

Look up a player

The examples use the api instance from above and a Paper or Minestom Player. Get the group a player belongs to. The result is null if no group matches:

val group = api.getPrimaryGroup(player.uniqueId).await()
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 what is currently shown for a player. The result includes every change made through the API:

val data = api.getPrefixData(player.uniqueId).await()
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())));

Method	Value
`getPrefix()`	Prefix
`getSuffix()`	Suffix
`getColor()`	Name color
`getDisplayName()`	Rendered name tag
`getChatFormat()`	Raw MiniMessage chat format
`getPriority()`	Tab list priority, higher is listed further up

Change how a player is shown

Change a player’s prefix, suffix, color, or tab list position for everyone. The changes apply to chat, the tab list, and the name tag.

api.setPrefix(player.uniqueId, Component.text("[Builder] ", NamedTextColor.GOLD))
api.setColor(player.uniqueId, NamedTextColor.GOLD)

api.setPrefix(player.getUniqueId(), Component.text("[Builder] ", NamedTextColor.GOLD));
api.setColor(player.getUniqueId(), NamedTextColor.GOLD);

Description	Method
Set the prefix	`setPrefix(id, prefix)`
Set the suffix	`setSuffix(id, suffix)`
Set the name color	`setColor(id, color)`
Set the tab list position	`setPriority(id, priority)`
Show the player with another group	`setGroup(id, group)`
Undo all changes	`reset(id)`

setGroup takes a PrefixesGroup or a group name. With a name, it completes with false if no group with that name exists:

val found = api.setGroup(player.uniqueId, "admin").await()
if (!found) println("The group admin does not exist")

api.setGroup(player.getUniqueId(), "admin").thenAccept(found -> {
    if (!found) System.out.println("The group admin does not exist");
});

Changes only work for online players and are removed when the player leaves the server. Set them again on join if they should stay.

Show a player differently to certain players

Per-viewer changes let different players see the same player differently. Use them for anything that depends on the relationship between two players:

Friends: a player sees their friends with a [Friend] prefix
Parties: party members see each other with a party prefix at the top of the tab list
Teams: in a minigame, each team sees its own members in green and enemies in red

Every set method and setGroup takes an optional viewers argument. Only those players see the change; everyone else keeps seeing the normal prefix. viewers is an Adventure Audience, so you can pass one player or several with Audience.audience(players). Show a friend with a [Friend] prefix, only to the player:

api.setPrefix(friend.uniqueId, Component.text("[Friend] ", NamedTextColor.GREEN), player)

api.setPrefix(friend.getUniqueId(), Component.text("[Friend] ", NamedTextColor.GREEN), player);

Show party members with a [Party] prefix at the top of the tab list, only to the party:

val party = Audience.audience(partyMembers)

partyMembers.forEach { member ->
    api.setPrefix(member.uniqueId, Component.text("[Party] ", NamedTextColor.LIGHT_PURPLE), party)
    api.setPriority(member.uniqueId, 1000, party)
}

Audience party = Audience.audience(partyMembers);

for (Player member : partyMembers) {
    api.setPrefix(member.getUniqueId(), Component.text("[Party] ", NamedTextColor.LIGHT_PURPLE), party);
    api.setPriority(member.getUniqueId(), 1000, party);
}

setGroup also accepts several targets at once. In a minigame, each team sees its own members with one group and the other team with another:

val red = Audience.audience(redTeam)
val blue = Audience.audience(blueTeam)

api.setGroup(red, "teammate", red)
api.setGroup(red, "enemy", blue)
api.setGroup(blue, "teammate", blue)
api.setGroup(blue, "enemy", red)

Audience red = Audience.audience(redTeam);
Audience blue = Audience.audience(blueTeam);

api.setGroup(red, "teammate", red);
api.setGroup(red, "enemy", blue);
api.setGroup(blue, "teammate", blue);
api.setGroup(blue, "enemy", red);

The groups teammate and enemy must exist in your group source. Use reset(targets, viewers) to remove only the changes that certain players see, for example when a friendship ends or a player leaves a party:

// The player no longer sees the [Friend] prefix
api.reset(friend, player)

// The party no longer sees the player as a member, and the other way around
api.reset(player, party)
api.reset(party, player)

// The player no longer sees the [Friend] prefix
api.reset(friend, player);

// The party no longer sees the player as a member, and the other way around
api.reset(player, party);
api.reset(party, player);

To check what one player sees, pass them as the viewer: api.getPrefixData(friend.uniqueId, player). If several changes apply, the change for a specific viewer wins over the change for everyone, which wins over the player’s group. Per-viewer changes are removed when either player leaves the server.

List and add groups

List all groups of the current group source, highest priority first:

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

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

Add a group with addGroup. With config, the group is saved to config.yml. With luckperms, it is created in LuckPerms. The future completes with false if a group with the same name already exists.

val created = api.addGroup(VipGroup()).await()
if (!created) println("A group named vip already exists")

api.addGroup(new VipGroup()).thenAccept(created -> {
    if (!created) System.out.println("A group named vip already exists");
});

Players get an added group like any other group, for example through its permission with config. A group implements PrefixesGroup:

Example: VipGroup

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 : PrefixesGroup {
    override val name = "vip"
    override val priority = 50
    override val permission = "simplecloud.prefix.group.vip"
    override val prefix = MiniMessage.miniMessage().deserialize("<#A3E635>VIP <#475569>| ")
    override val suffix = Component.empty()
    override val color = TextColor.color(0xA3E635)
    override val displayName = "<color><playername>"
    override val chatFormat = "<prefix><color><playername><suffix> <#475569>» <#F8FAFC><message>"

    // Only used when this group is part of a custom group provider
    override fun containsPlayer(id: UUID): CompletableFuture<Boolean> =
        CompletableFuture.completedFuture(false)
}

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;

public final class VipGroup implements PrefixesGroup {

    @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.color(0xA3E635);
    }

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

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

    // Only used when this group is part of a custom group provider
    @Override
    public CompletableFuture<Boolean> containsPlayer(UUID id) {
        return CompletableFuture.completedFuture(false);
    }
}

Create a group provider

A group provider decides which groups exist and which group a player belongs to. Prefixes includes the config and luckperms providers. Create your own provider to take groups from your plugin, for example from your own role system. Implement GroupProvider. This example keeps its groups and the team of each player in memory:

import app.simplecloud.prefixes.api.group.GroupProvider
import app.simplecloud.prefixes.api.group.PrefixesGroup
import java.util.UUID
import java.util.concurrent.CompletableFuture
import java.util.concurrent.ConcurrentHashMap

class TeamGroupProvider : GroupProvider {
    private val groups = ConcurrentHashMap<String, PrefixesGroup>()
    private val teams = ConcurrentHashMap<UUID, String>()

    fun setTeam(id: UUID, team: String) {
        teams[id] = team
    }

    // Name used in general.source
    override fun getName() = "teams"

    override fun getGroups(): CompletableFuture<Collection<PrefixesGroup>> =
        CompletableFuture.completedFuture(groups.values.sortedByDescending { it.priority })

    override fun getGroup(id: UUID): CompletableFuture<PrefixesGroup?> {
        val team = teams[id] ?: return CompletableFuture.completedFuture(null)
        return CompletableFuture.completedFuture(groups[team])
    }

    override fun addGroup(group: PrefixesGroup): CompletableFuture<Boolean> =
        CompletableFuture.completedFuture(groups.putIfAbsent(group.name, group) == null)
}

import app.simplecloud.prefixes.api.group.GroupProvider;
import app.simplecloud.prefixes.api.group.PrefixesGroup;

import java.util.Collection;
import java.util.Comparator;
import java.util.Map;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ConcurrentHashMap;

public final class TeamGroupProvider implements GroupProvider {
    private final Map<String, PrefixesGroup> groups = new ConcurrentHashMap<>();
    private final Map<UUID, String> teams = new ConcurrentHashMap<>();

    public void setTeam(UUID id, String team) {
        teams.put(id, team);
    }

    // Name used in general.source
    @Override
    public String getName() {
        return "teams";
    }

    @Override
    public CompletableFuture<Collection<PrefixesGroup>> getGroups() {
        return CompletableFuture.completedFuture(groups.values().stream()
            .sorted(Comparator.comparingInt(PrefixesGroup::getPriority).reversed())
            .toList());
    }

    @Override
    public CompletableFuture<PrefixesGroup> getGroup(UUID id) {
        String team = teams.get(id);
        return CompletableFuture.completedFuture(team == null ? null : groups.get(team));
    }

    @Override
    public CompletableFuture<Boolean> addGroup(PrefixesGroup group) {
        return CompletableFuture.completedFuture(groups.putIfAbsent(group.getName(), group) == null);
    }
}

config.yml

general:
  source: teams

val teams = TeamGroupProvider()
api.registerGroupProvider(teams)

// Load the groups of players who are already online from the new provider
api.refreshAll()

TeamGroupProvider teams = new TeamGroupProvider();
api.registerGroupProvider(teams);

// Load the groups of players who are already online from the new provider
api.refreshAll();

Prefixes does not know when your plugin changes a player’s group. Call refreshPlayer afterwards so the new group is shown. Changes made through the API stay in place.

teams.setTeam(player.uniqueId, "red")
api.refreshPlayer(player.uniqueId)

teams.setTeam(player.getUniqueId(), "red");
api.refreshPlayer(player.getUniqueId());

See the built-in providers on GitHub for complete implementations, including the LuckPerms provider.

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
Use the viewers argument for friends, parties, and teams instead of creating a group for each

Introduction

Setup

Configuration

Plugins

Supported software

Install the plugin

Configuration

config.yml

Group sources

Placeholders

Feature switches

Cross-server sync

Commands

API

Add the dependency

Access the API

Look up a player

Change how a player is shown

Show a player differently to certain players

List and add groups

Create a group provider

Best practices

​Supported software

​Install the plugin

​Configuration

​config.yml

​Group sources

​Placeholders

​Feature switches

​Cross-server sync

​Commands

​API

​Add the dependency

​Access the API

​Look up a player

​Change how a player is shown

​Show a player differently to certain players

​List and add groups

​Create a group provider

​Best practices

Supported software

Install the plugin

Configuration

config.yml

Group sources

Placeholders

Feature switches

Cross-server sync

Commands

API

Add the dependency

Access the API

Look up a player

Change how a player is shown

Show a player differently to certain players

List and add groups

Create a group provider

Best practices