ServerRoles

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.

Permissions

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

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.