Hierarchy

Hierarchy

Permissions, chat and tab list in one plugin — for Bukkit, Spigot, Paper and BungeeCord, from Minecraft 1.19 up to the current release.

Hierarchy manages ranks with weights and inheritance, writes prefixes and suffixes into the chat and the player list, and stores everything either in plain YAML files or in a shared MySQL database. Every message exists in English and German.

• One jar for all platforms — the same file works as a server plugin and as a BungeeCord plugin
• Wildcards (essentials.*), negated nodes (-worldedit.command), per-world and per-server scopes, temporary ranks and temporary permissions
• Chat format and tab list format per group, animated tab header and footer
• Tab list sorted by rank weight
• YAML or MySQL, with live synchronisation between servers and a one-command migration between both
• Vault permission and chat provider, optional PlaceholderAPI support
• No external services, no telemetry

Install

Server (Bukkit, Spigot, Paper)

1. Drop hierarchy.jar into plugins/.
2. Start the server. config.yml, groups.yml and lang/ are created in plugins/Hierarchy/.
3. Give your staff hierarchy.admin, for example with /hr user group set <name> admin.

Proxy (BungeeCord, Waterfall)

1. Drop the same hierarchy.jar into the proxy plugins/ folder.
2. Start the proxy. Its own plugins/Hierarchy/ folder is created.
3. Point both the proxy and all backend servers at the same MySQL database so ranks are shared (see Storage).

Requirements: Java 17 or newer, Minecraft 1.19 or newer. MySQL is optional; the driver is downloaded by the server on first start and only used when storage.type is set to mysql.

First steps

groups.yml ships with a working ladder:

Everybody who is not in any group is treated as a member of the group marked default: true.

/hr group create builder 250
/hr group set builder prefix &b[Builder] &b
/hr group parent add builder default
/hr group permission add builder worldedit.*
/hr user group set Notch builder

Commands

/hierarchy with the aliases /hr, /perm and /rank.

Players do not have to be online. Offline players are looked up in the storage and in the server's player cache.

Properties for /hr group set

Use - or none as the value to clear a property.

Flags for permission commands

Durations accept s, m, h, d, w and y and can be combined: 1d12h. A plain number means minutes.

/hr group permission add vip essentials.fly world=creative
/hr group permission add vip -essentials.tpa
/hr user permission add Notch worldedit.* 7d
/hr user group add Notch vip 30d

How permissions are resolved

1. All non-expired group memberships are collected; without any membership the default group is used.
2. Inherited groups are applied first, then the group itself, groups with a higher weight after those with a lower one.
3. The player's own nodes are applied last and always win.
4. A check first looks for the exact node, then for a.b.*, a.* and finally *.
5. If nothing matches, the decision is left to the server, so plugin.yml defaults and operator status still work.

Negated nodes (-node or false) are real denials. They beat a wildcard from a lower priority, which is how you take single commands away from an inherited rank.

Chat

chat:
  enabled: true
  format: '%prefix%%player%%suffix% &8» &f%message%'
  per-world: false
  color-permission: hierarchy.chat.color
  placeholderapi: true
  log-to-console: true

A group with a chat-format of its own overrides chat.format. Players with hierarchy.chat.color may use colour codes in their messages; for everyone else the codes are removed. With per-world: true a message only reaches players in the same world.

Hierarchy cancels the original chat event and sends the formatted line itself. On Paper the component chat event is used, on Spigot and Bukkit the classic one. Plugins that only listen for chat to display it will therefore not see the message a second time — chat loggers that read at MONITOR priority still do.

Tab list

tab:
  enabled: true
  name-format: '%prefix%%player%'
  sort-by-weight: true
  update-ticks: 40
  animation-ticks: 20
  header:
    - '&b&lSERVER'
    - '&3&lSERVER'
  footer:
    - '&7Online &f%online%&7/&f%max%   &7Ping &f%ping%ms'

Several header or footer lines are played one after another, one frame every animation-ticks. update-ticks controls how often names, ping and online numbers are refreshed.

Sorting uses teams on the server's main scoreboard, named after the group weight. Every team Hierarchy creates starts with hy and is removed again when the plugin stops.

On a proxy only header and footer are applied — names in the player list belong to the backend server.

Placeholders

Colours: &a style codes everywhere plus hex as &#ff8800 or <#ff8800>. With PlaceholderAPI installed, its placeholders work in every format too.

Storage

storage:
  type: yaml
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ''
    table-prefix: hierarchy_
    use-ssl: false
    pool-size: 6
    sync-seconds: 15
    jdbc-url: ''

yaml keeps groups.yml and users.yml next to config.yml. Good for a single server.

mysql keeps six tables (hierarchy_groups, hierarchy_group_permissions, hierarchy_users, hierarchy_user_groups, hierarchy_user_permissions, hierarchy_meta) and is the right choice for networks and for large player counts. Tables are created automatically. MariaDB works as well; jdbc-url replaces host, port, database and SSL settings when you need a custom one.

Every write raises a revision counter. All other servers notice it within sync-seconds and reload groups and online players, so a rank given on one server is live everywhere. 0 turns the check off.

If the database cannot be reached at start, Hierarchy logs the reason and falls back to YAML instead of leaving the server without permissions.

/hr migrate mysql copies all groups and players into the database, /hr migrate yaml the other way around. Afterwards set storage.type and run /hr reload.

Networks

Give every server a name:

server: lobby

That name is what server= scopes are matched against, so one database can hold essentials.fly#creative for one server and nothing for the others. The proxy handles permissions for proxy commands and the tab header; chat and the player list are formatted by the backend servers.

Permission nodes

Vault

With Vault installed, Hierarchy registers both the permission and the chat provider, so plugins that ask Vault for groups, prefixes or suffixes get the right answers. Nothing to configure; vault: false in config.yml turns the registration off.

Language

language: en or language: de in config.yml. Both files live in plugins/Hierarchy/lang/ and can be edited; new keys from an update are filled in from the bundled English file. A third language is just another file, for example lang/fr.yml with language: fr.

Other settings

permissions:
  inject: true
  default-group: default

display-name:
  enabled: true
  format: '%prefix%%player%%suffix%'

join-quit:
  enabled: false
  join: '&8[&a+&8] %prefix%%player%'
  quit: '&8[&c-&8] %prefix%%player%'

permissions.inject replaces the permission handler of every player so that wildcards and denials work for all plugins, not only for Hierarchy's own commands. It is the recommended setting; if a server version does not allow it, Hierarchy says so in the log and falls back to permission attachments, which expand wildcards only against nodes that plugins have registered.

display-name writes prefix and suffix into the name used by /list and by other plugins. join-quit replaces the vanilla join and quit messages; an empty format hides them.

Developer API

import org.hierarchy.api.HierarchyApi;
import org.hierarchy.api.HierarchyProvider;

if (HierarchyProvider.available()) {
    HierarchyApi hierarchy = HierarchyProvider.get();
    String group = hierarchy.primaryGroup(player.getUniqueId());
    String prefix = hierarchy.prefix(player.getUniqueId());
    hierarchy.addGroup(player.getUniqueId(), "vip", System.currentTimeMillis() + 86_400_000L);
}

The interface also offers check, suffix, weight, groupsOf, groups, removeGroup, setPermission, unsetPermission and reload. Write access saves to the storage in the background and refreshes chat, tab list and permissions of the player right away.

Build from source

./gradlew :hierarchy:build

The jar and a sources jar end up in hierarchy/build/libs. Compiled against Spigot API 1.19.4, BungeeCord API and Java 17, so the same build runs on every supported platform and version.