zPermissions — A Superperms plugin for Bukkit

zPermissions is primarily an SQL database-backed Superperms (aka Bukkit permissions) implementation. It also supports flat-file storage. Notable features are: multi-world support, ranks with multiple tracks/ladders, group inheritance of arbitrary depth (within reason), and optional region-specific permissions using WorldGuard regions, Residence residences, or Factions territories.

There is no built-in build protection (I rely on other plugins for that). zPermissions focuses on permissions and only permissions.

I aim to keep zPermissions a simple, yet feature-rich, Superperms provider.

Please post bugs and/or feature requests as dev.bukkit.org tickets. But before doing so, please check the known issues as well as the FAQ.

[ Quick start documentation | For Server Admins | FAQ | More documentation below! ]

zPermissions currently does not support UUIDs. However, support is planned for the 1.3 release. Testers wanted! See this comment for details.


  • A variety of storage options, from SQL to flat-file. Uses Bukkit database to store permissions (i.e. settings in bukkit.yml). Should work with most databases supported by Avaje Ebean — I've specifically tested with PostgreSQL, MySQL, and H2. The default Bukkit database, SQLite, is not supported. zPermissions will automatically fall back to flat-file storage if it is used.

  • Group inheritance. Groups may inherit permissions from a multiple parent groups.

  • Players may be members of more than one group. The order of which group permissions are applied is well defined and based on group weight (which is configurable, of course).

  • Multi-world support. Permissions granted to players and groups may be associated with a specific world.

  • Optional region support. Permissions may also be associated with WorldGuard regions or Residence residences.

  • Multiple promotion tracks! Using permissions, you can also limit who can promote/demote others and which tracks they may use. In addition, each player may be promoted/demoted along multiple tracks.

  • Short-term temporary permissions. Give a player a permission node that lasts anywhere from a few seconds to a few minutes.

  • Temporary group assignments. Assign a group to a player and have their membership expire after 1 day... a few months... or a year! Whatever duration you want.

  • Players and groups can be assigned chat prefixes and suffixes. A Vault-compatible chat-formatting plugin is still required, like Herochat, zChat, etc.

  • API. zPermissions offers a comprehensive read-only API that other plugins can use. (Though I would recommend coding against Vault instead.)

  • Metadata support. Players and groups may have arbitrary metadata associated with them. Metadata values may be strings, integers, reals (floating point), and booleans. Metadata may be queried via the native API or Vault Chat API.

  • Automatic group permissions. With the advent of Superperms/Bukkit permissions, the recommended way of testing group membership is by using permissions. zPermissions can automatically set a permission based on the group's name for each group. By default, this configurable permission is group.<groupname> (compatible out-of-the-box with WorldEdit and WorldGuard!).

  • Re-assignable default group. The default group (the group assigned to players who have not been explicitly placed into any groups) is named default. This may be changed.


  • Groups are "universal" — across all worlds. There are no plans to introduce world-specific groups.

  • However, players and groups may have world-specific and/or region-specific permissions. These permissions are only in effect when the player is in that particular world and/or region.

  • There are 4 "levels" of permissions: universal, world-specific, region-specific, and finally region- and world-specific. The most general permissions are applied first, with all group permissions applied first finally followed by player permissions:

    1. Universal group permissions
    2. World-specific group permissions
    3. Region-specific group permissions
    4. Region- and world-specific group permissions
    5. Universal player permissions
    6. World-specific player permissions
    7. Region-specific player permissions
    8. Region- and world-specific player permissions
  • Players may be members of multiple groups. Groups may be assigned a weight — a higher weight means the group is applied later so it overrides earlier groups. Groups with the same weight are applied alphabetically.

  • Groups may inherit from one or more parent groups. A group's parents are applied in reverse order so that a group's first parent overrides all subsequent parents.

Installation & Usage

Put zPermissions.jar in your server's plugins directory. Start up your server. This will create the file config.yml in your server's plugins/zPermissions directory. You may want to edit this file to set your default group and default track. You may also want to create your tracks.

Type /permissions to get started. (/perm or /p may also work, if those aliases are available.)

The permission nodes in the get, set, and unset sub-commands may be specified as:

  • <permission> — An unqualified permission node applies to all worlds and all regions.
  • <world>:<permission> — To make a permission world-specific, prefix it with the world name followed by a colon.
  • <region>/<permission> — To make a permission region-specific, prefix it with the region name followed by a slash.
  • <region>/<world>:<permission> — You may also make a permission both region- and world-specific by combining the two qualifiers. For now, the region qualifier must always come first.

The rank commands are /promote, /demote, /setrank, and /unsetrank and will normally broadcast changes to all admins. The rank commands have an option -q to operate silently, e.g. when being called by automated processes. They will, however, still log their actions to the server log for security audit purposes. Opposite of -q, they will also take -Q which causes the rank commands to broadcast changes to all users.

More Documentation

License & Source

zPermissions is released under the Apache License, Version 2.0.

Sources may be found on GitHub:

Development builds of this project can be acquired at the provided continuous integration server.
These builds have not been approved by the BukkitDev staff. Use them at your own risk.

To Do

  • More extensive unit tests, especially on the service interface.
  • Better organized docs.

You must login to post a comment. Don't have an account? Register to get one!

  • Avatar of Iwitrag Iwitrag Apr 23, 2014 at 08:49 UTC - 0 likes

    @ZerothAngel: Go

    I understand now :) It's a nice workaround ! Thank you very much!

  • Avatar of ZerothAngel ZerothAngel Apr 23, 2014 at 02:25 UTC - 1 like

    @Iwitrag: Go

    You misunderstand. I said the workaround is to not use permanent memberships. Instead use something ridiculous but finite, like 10 years. Who cares then if you add a month or a day or whatever to 10 years? It would basically be the same as adding a small amount to a permanent membership.

    And I know you don't want to remove the membership first. I was saying that would be required in order to reset the membership to a shorter expiration, which is possible now.

    You may think it's a bug, but when the original "adding-time" feature was requested, the current behavior was part of the specifications. I'm not breaking backwards compatibility. Instead, your feature request will use a different switch (-A, capital A). But like I said, 1.3 is focused on UUID only. So your feature will come afterwards, it doesn't really warrant the effort branching 1.2 (both for me to backport the feature to 1.2 and for the DBO staff to review another release), especially when a workaround exists.


  • Avatar of Iwitrag Iwitrag Apr 23, 2014 at 01:09 UTC - 0 likes

    @ZerothAngel: Go

    So it's impossible to add time to permanent membership without destroying it for that player.

    I don't want to add 10 years of VIP to player who voted 100 times for my server and it's not possible to make rewards different for VIP's and non-VIP's ... I think it's bug because infinity + something = infinity.

    "Because otherwise there's no way to reset a permanent membership without removing it first." I don't want to remove membership, I want to add time to permanent membership (well, not really, but there may be players who is VIP and when he votes for 100th time, it will reset his VIP, which is not what I want).

    Workaround may be new group something like VIP2 with same permissions inherited from default VIP and only obtainable via rewards (unable to buy it - so players won't lose their bought VIP's)...

    But it's not really good workaround, because this will not extend VIP duration for players, who has VIP e.g. for month.

    Last edited Apr 23, 2014 by Iwitrag
  • Avatar of ZerothAngel ZerothAngel Apr 22, 2014 at 22:03 UTC - 0 likes

    @Iwitrag: Go

    That's intended and is how all the membership commands work. Because otherwise there's no way to reset a permanent membership without removing it first. I suppose I can add yet another option to those commands, but that's not happening anytime soon. You've been posting your feature requests/bug reports in the general comments area, and that's a really bad place. I suggest you open a ticket...

    Anyway, as a workaround for now, why not set their membership to something like 10 years. Then additions will work as expected. For now, I don't recommend using permanent & temporary membership commands on the same group.

  • Avatar of Iwitrag Iwitrag Apr 22, 2014 at 21:28 UTC - 0 likes

    Hello, I have big problem - I'm using /perm player xx addgroup -a VIP in votifier / GA listener to give players 10 days VIP when reached 100 votes - but there is problem - if a player is VIP for forever, it will not add 10 days VIP (so it will be still forever) but it SET VIP to 10 days.

    Can you fix this please?

  • Avatar of ZerothAngel ZerothAngel Apr 22, 2014 at 01:39 UTC - 0 likes

    @LordKainzo: Go

    That's an old option that was removed before 1.0, maybe earlier. Should be safe to remove now, as it doesn't do anything anymore.

    And you probably already know this from testing on your test server, but before you deploy 1.2a, be sure log-vault-changes is false.

  • Avatar of LordKainzo LordKainzo Apr 21, 2014 at 22:32 UTC - 0 likes

    @ZerothAngel: Go

    optimize-set-permissions: false

    So what's this do exactly? we have a pretty hefty permission file and not sure yet :) - btw im throwing in 1.2a to live and seeing if any issues arise.

  • Avatar of EdyTheCow EdyTheCow Apr 21, 2014 at 15:29 UTC - 0 likes

    @ZerothAngel: Go

    You can always use permissions.yml for per server permissions. Works pretty well for me :)


  • Avatar of ZerothAngel ZerothAngel Apr 18, 2014 at 19:14 UTC - 0 likes

    @DanSpedey: Go

    See "Installation & Usage" above. Per-world is supported, per-server, no.

  • Avatar of DanSpedey DanSpedey Apr 18, 2014 at 08:19 UTC - 0 likes

    How do you add permissions to certain worlds/servers only?



Date created
Sep 13, 2011
Last update
Apr 08, 2014
Development stage
  • enUS
Apache License version 2.0
Curse link
Recent files
  • R: 1.2a for CB 1.7.2-R0.3 Apr 08, 2014
  • R: 1.1.1 for CB 1.7.2-R0.2 Jan 09, 2014
  • R: 1.1 for 1.6.4 Oct 06, 2013
  • R: 1.0.1a for 1.6.2 Jul 29, 2013
  • R: 1.0 for 1.6.1 Jun 15, 2013



Optional dependency