ServerRoles

A modern, lightweight role-based permission manager for Paper/Purpur 1.21.x (Java 21).

Version 1.0.0 · Minecraft 1.21 – 1.21.11 · 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 1.21+ and Java 21.
2. Optional: PlaceholderAPI for placeholder output.
3. Drop ServerRoles-1.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.