SimpleCloud Prefixes Plugin

Prefixes is a plugin/extension that manages prefixes and suffixes in tab, and formats the chat to your liking. API methods for doing this are also provided. You can implement it on your own, or use the default implementation for LuckPerms. For prefixes and suffixes, Adventure Components are used, as well as MiniMessage in the LuckPerms default implementation.

Download

Supported server versions

A list of all supported server versions. If your server version is listed here, it means that this plugin is supported and maintained on your server version.

Server type	PrefixesApi	LuckPerms	out of the box
Paper and Forks	✅	✅	✅
Spigot and Forks	✅	✅	✅
Minestom	✅	❌	❌ (you can easily get it working by using your own implementation)

Configuration

There two ways to configure the plugin. You can configure the player display name using LuckPerms. The chat format is configured using the configuration.

LuckPerms

Prefixes will automatically register any LuckPerms Group as a PrefixGroup, alongside its prefix, suffix, and TeamColor.

Setting a groups prefix/suffix

/lp group <groupname> meta addprefix/addsuffix <weight> <prefix/suffix in MiniMessage format>

Setting a groups TeamColor

Depending on what server version your on, you have to set a hex value or a ChatColor enum as color. On Spigot, color should be in ChatColor format (e.g. WHITE). On every other server implementation you can use hex colors

/lp group <groupname> meta set color <color>

Chat configuration

The config.json file is located in the data folder. It will look like this:

{
  "chatFormat": "<prefix><name_colored><suffix><gray>:</gray> <white><message></white>"
}

You can configure the chat message format by editing the value of chatFormat. MiniMessage is used, to provide quick and easy color and gradient support to the format. There also are placeholders you can use for the format:

Placeholder	Value
name	The players name
name_colored	The players name, colored the same way as in the scoreboard
prefix	The players prefix
suffix	The players suffix
message	The sent message

API usage

You can use the API to directly modify prefixes and groups through third party plugins.

Getting PrefixesAPI

To use the API, you need to get the PrefixesAPI instance.

Bukkit/Paper

When Prefixes is active, a bukkit service provider is registered containing the Api object. To get it, use the following code.

val prefixesApiProvider: RegisteredServiceProvider<PrefixesApi>? = Bukkit.getServicesManager().getRegisteredServiceProvider(PrefixesApi::class.java)
if (prefixesApiProvider != null) {
    val myPrefixesApi: PrefixesApi = prefixesApiProvider.provider
    //Code using the PrefixesApi
}

IMPORTANT: To make sure everything works as expected, add PrefixesApi to your plugin.yml depends list.

Minestom

To get the PrefixesApi object on Minestom, you need to call the getApi() Singleton in the PrefixesExtension class.

val myPrefixesApi: PrefixesApi = PrefixesExtension.getApi()
//Code using the PrefixesApi

IMPORTANT: To make sure everything works as expected, add PrefixesApi to your extension.json dependencies array.

Using the API

Now that you have a PrefixesApi object, you have access to all of these Functions:

    /**
     * Sets the prefix and suffix of a player in both Tab and Chat
     * @param uniqueId UUID of the target player
     * @param group
     */
    fun setWholeName(uniqueId: UUID, group: PrefixesGroup)

    /**
     * Sets the prefix and suffix of a player in both Tab and Chat
     * @param uniqueId UUID of the target player
     * @param groupName
     */
    fun setWholeName(uniqueId: UUID, groupName: String)

    /**
     * Sets the prefix of a player in both Tab and Chat
     * @param uniqueId UUID of the target player
     * @param prefix prefix to set
     */
    fun setPrefix(uniqueId: UUID, prefix: Component)

    /**
     * Sets the prefix of a player in both Tab and Chat
     * @param uniqueId UUID of the target player
     * @param suffix suffix to set
     */
    fun setSuffix(uniqueId: UUID, suffix: Component)

    /**
     * Returns all registered PrefixesGroup ordered by priority
     */
    fun getGroups(): List<PrefixesGroup>

    /**
     * Returns the highest PrefixesGroup of a player
     * @param uniqueId UUID of the target player
     */
    fun getHighestGroup(uniqueId: UUID): PrefixesGroup

    /**
     * Adds a [PrefixesGroup]
     * @param group
     */
    fun addGroup(group: PrefixesGroup)

    /**
     * Changes the PrefixesActor of the server instance (e.g. to a bukkit actor)
     * @param actor
     */
    fun setActor(actor: PrefixesActor)

    /**
     * Changes the Scoreboard Team color of the target player (Used in 1.12+ to make player names colorful)
     * @param uniqueId UUID of the target player
     * @param color Color string (ChatColor on spigot, hex colors on other server implementations)
     */
    fun setColor(uniqueId: UUID, color: String)

    /**
     * Sets the used PrefixesConfig
     * @param config Specifies the new [PrefixesConfig]
     */
    fun setConfig(config: PrefixesConfig)

Own implementation

PrefixesApi supports the reimplementation of features through third-party Plugins.

PrefixesGroup

The interface PrefixesGroup provides the structure to all necessary features for a PrefixesGroup. By implementing it in a custom class, you can add this group to the PrefixesApi by calling the addGroup function.

Example group implementation

class MyPrefixesGroup : PrefixesGroup {
    override fun getName(): String {
        return "mygroup"
    }

    override fun getPrefix(): Component {
        return Component.text("")
    }

    override fun getColor(): String {
        return "WHITE"
    }

    override fun getSuffix(): Component {
        return Component.text("")
    }

    override fun getPriority(): Int {
        return 0
    }

    override fun containsPlayer(uniqueId: UUID): Boolean {
        //Custom contains player logic
    }

    override fun containsPlayerFuture(uniqueId: UUID): CompletableFuture<Boolean> {
        //Custom async contains player logic
    }
}

PrefixesActor

A PrefixesActor is responsible for applying, and unapplying groups and prefixes as well as suffixes from players. It also manages Chat-Message formatting. To enable your custom PrefixesActor, you have to call the setActor function on the PrefixesApi object.

Example actor implementation

class MyPrefixesActor : PrefixesActor {
    override fun applyGroup(
        target: UUID,
        group: PrefixesGroup
    ) {
        //Custom group apply logic
    }

    override fun remove(target: UUID) {
        //Custom remove logic
    }

    override fun setPrefix(target: UUID, prefix: Component) {
        //Custom prefix apply logic
    }

    override fun setSuffix(target: UUID, suffix: Component) {
        //Custom suffix apply logic
    }

    override fun formatMessage(target: UUID, format: String, message: Component): Component {
        //Custom chat formatting logic
    }

    override fun setColor(target: UUID, color: String) {
        //Custom color apply logic
    }
}

Custom plugin implementation

If you want to make breaking changes to the plugin, you have to code your own implementation.

Creating API and indexing groups

To create an API object, you need to implement PrefixesApiImpl. From there, overwriting the indexGroups adds parsing groups from anywhere

Example API implementation

class MyApiImplementation : PrefixesApiImpl() {
    override fun indexGroups() {
        //Custom group parsing implementation
    }
}

From there, you can register this as a service provider in your custom plugin.

IMPORTANT: You still need to register the events on your own! Take a look at the source code to see how this is done.