ServerRoles

A modern, lightweight role-based permission manager for Paper/Purpur 26.3 (Java 25).

Version 2.1.0 · Minecraft 26.3 · Server-side

ServerRoles manages roles, permissions, prefixes and chat formatting through a single /role command. Roles support hex-color prefixes, inheritance, priorities, an OP flag, and both permanent and temporary player assignments. Storage is pluggable between YAML, SQLite and MySQL.

Features

• Role management. Create and delete roles; set prefix, hex color, OP flag, priority and permissions.
• Inheritance. Roles inherit from a parent; permissions resolve bottom-up (child overrides parent) with negated nodes prefixed by -. Circular inheritance is detected at load time and when setting a parent.
• Player assignments. Assign roles permanently or temporarily with a duration (e.g. 1d, 24h, 1d12h); temporary roles are expired by a repeating main-thread task.
• Chat formatting. Optionally format chat with the player's role prefix and color.
• Pluggable storage. YAML, SQLite or MySQL (HikariCP, shaded and relocated).
• PlaceholderAPI expansion for role data.
• Developer API. ServerRolesProvider exposes the API; PlayerRoleChangeEvent is cancellable.
• Localization. Bundled en_US and pt_PT (MiniMessage). A default role is auto-created if missing and cannot be deleted.

Commands

Single command /role with aliases /roles and /sr. All subcommands require serverroles.admin.

Command	Description	Permission
/role create <id> <displayName> <priority>	Create a role.	serverroles.admin
/role delete <id>	Delete a role.	serverroles.admin
/role list	List all roles.	serverroles.admin
/role info <id>	Show role details.	serverroles.admin
/role setprefix <id> <prefix>	Set a role's prefix.	serverroles.admin
/role setcolor <id> <#rrggbb>	Set a role's hex color.	serverroles.admin
/role setop <id> <true|false>	Set a role's OP flag.	serverroles.admin
/role setpriority <id> <number>	Set a role's priority.	serverroles.admin
/role setparent <id> <parentId>	Set a role's parent for inheritance.	serverroles.admin
/role addperm <id> <node>	Add a permission node to a role.	serverroles.admin
/role removeperm <id> <node>	Remove a permission node from a role.	serverroles.admin
/role listperms <id>	List a role's permission nodes.	serverroles.admin
/role assign <player> <id>	Assign a role to a player.	serverroles.admin
/role assigntemp <player> <id> <duration>	Assign a temporary role.	serverroles.admin
/role remove <player>	Reset a player to the default role.	serverroles.admin
/role check <player>	Check a player's role.	serverroles.admin
/role reload	Reload config, roles and players.	serverroles.admin
/role papi	Show PlaceholderAPI registration status.	serverroles.admin

Permissions

Node	Description	Default
serverroles.admin	Access to all ServerRoles admin commands.	op
serverroles.user	Basic user permission.	true

Configuration

language: en_US          # bundled: en_US, pt_PT
default-role: player     # given to new players; also the reset target

storage:
  type: yaml             # yaml | sqlite | mysql
  mysql:
    host: localhost
    port: 3306
    database: serverroles
    username: root
    password: password

features:
  chat-format: true      # format chat with the player's role prefix and color

Security notes

ServerRoles applies whatever permission nodes a role carries, and role OP status is applied with player.setOp(...). Keep these operational points in mind:

• There is a single admin node (serverroles.admin) with no internal hierarchy. Granting serverroles.admin (or an OP role) to a staff role effectively grants full control of the plugin, including the ability to assign OP. Do not add serverroles.admin, * or op-granting nodes to non-trusted roles.
• OP is applied and cleared through Bukkit's ops.json. Prefer to manage OP exclusively through this plugin, and avoid the OP flag on temporary roles.

Installation

1. Requires Paper or Purpur 26.3 and Java 25 (2.0.0 runs on 26.2, 1.x on 1.21.x).
2. Optional: PlaceholderAPI for placeholder output.
3. Drop ServerRoles-2.0.0.jar into plugins/ and start the server to generate config.yml.
4. Choose a storage backend, set your default-role, then run /role reload.

Dependencies

Plugin	Purpose
PlaceholderAPI	Optional placeholder output.

HikariCP (for SQLite/MySQL) is shaded into the jar; no extra install is required.

Support / Source

Source and issues: https://github.com/henriquescrrrr/carrageis-serverroles

License

Released under the GNU General Public License v3.0. See LICENSE.