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.
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.
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:
- Universal group permissions
- World-specific group permissions
- Region-specific group permissions
- Region- and world-specific group permissions
- Universal player permissions
- World-specific player permissions
- Region-specific player permissions
- 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.
/permissions to get started. (
/p may also work, if those aliases are available.)
The permission nodes in the
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
/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.
- Detailed Command Usage
- Temporary Permissions & Groups
- Customizing Table Names
- Vault Support
- For Plugin Developers
- Schema Updates
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.
- zPermissions (Requires ToHPluginUtils.jar)
- zPermissions-standlone (includes ToHPluginUtils, like the version distributed on dev.bukkit.org)
- More extensive unit tests, especially on the service interface.
- Better organized docs.
This version requires a schema update. If you're using one of the 3 supported databases, this should occur automatically. However, please read that page for precautions to take. Also see the "Data Versioning" section below.
This version adds new config.yml options:
This version adds new permissions:
The old permissions zpermissions.player and zpermissions.group are now deprecated. For the time being, they will remain as aliases for the "wildcard" versions (zpermissions.player.* and zpermissions.group.* respectively). Also see the permissions documentation.
- Allow world argument to getPlayerPermissions() and getGroupPermissions() API methods to be null. This also fixes a bug with the playerHas() and groupHas() implementations for Vault.
- Keep track of "data version." Add ability to refresh from database conditionally.
- Add basic support for world mirroring.
- Use finer-grained permissions to control "/permissions player" and "/permissions group" commands.
- Add equivalent sub-commands (addgroup/removegroup) under player to add/remove players to/from groups.
- Add ZPermissionsRankChangeEvent, a Bukkit event fired off upon successful completion of a rank command (promote, demote, setrank, unsetrank).
- Add region manager support based on Factions roles/relations.
- Add -m/--members-only option to group..purge command.
To better support multi-server installations, zPermissions will now maintain a version number for the data in the database schema. A new table will be created named DATA_VERSION by default. (If you wish it to be named something else, you are advised to update config.yml before running the new version.)
This new table will normally contain a single row: the version number. All operations made through zPermissions that update the database will increment this version number.
The /permissions refresh command will now accept a new option flag: --conditional (which can be abbreviated simply as -c)
When run with this option, zPermissions will first check the data version in the database and compare it with the data version it was last initialized or refreshed with. If the versions are different, the refresh will be performed. Otherwise nothing happens.
This extends to the auto-refresh-interval option in config.yml. With this new version of zPermissions, the refreshes performed by setting auto-refresh-interval to a positive integer (representing the interval in minutes) will now be conditional. (This can be changed with the new auto-refresh-force option.)
The load on your server (and database) caused by the auto-refresh feature should now be significantly less. To synchronize servers, you can probably get away with much shorter intervals — like 5-10 minutes — or even 1 minute if you're absolutely sure zPermissions can load from the database fast enough (when zPermissions starts up, it will report how quickly it loaded your permissions which should give you an idea).
If you are making external modifications to the database schema while using the auto-refresh-interval option, then it is recommended that you change your process so you also increment the version number in the DATA_VERSION table. If this isn't possible, you can also switch auto-refresh-force to true to preserve the pre-1.1 behavior of auto-refresh. (That is, refreshes are done unconditionally at the defined interval.)
World mirroring is a configuration option where you can define that permissions in one particular world will simply mirror that of another.
To set it up, simply add a section like the following to config.yml:mirrors: world: - world_nether - world_the_end creative: - creative_nether
In the above example, permissions for "world_nether" and "world_the_end" simply mirror permissions on "world." And permissions for "creative_nether" mirrors those on "creative."
Even if you have world mirroring enabled for a particular world you can still have world-specific permissions for that world. These world-specific permissions will always override the permissions from the mirrored world.
A new option named vault-metadata-includes-group has been added. It is similar to the already-existing vault-prefix-includes-group. It defaults to true, changing the pre-1.1 behavior.
When true, the Vault methods getPlayerInfo*() will fall back to returning metadata from the player's primary group, if present. This is to address issues with other plugins that don't do this fallback behavior themselves.
Region-specific permissions for Factions territories has been added. However, for Factions, it's a bit special. When setting permissions, the region names you use should be based on Factions roles/relations, e.g.:/perm group default set leader/foo.bar
This means that all Faction leaders (assuming they are in the "default" group directly or through inheritance) will have the foo.bar permission node when they are in their own territory.
The exact names of all roles/relations are:leader officer member recruit ally truce neutral enemy
Note that if you are using Factions with other supported region plugins (e.g. WorldGuard), you will probably have to edit the region-managers option so that Factions is detected first.
|File Name||Release Type||Game Version||Downloads||Date|
- Admin Tools, Anti-Griefing Tools, Informational, Teleportation, and World Editing and Management
- 143,383 Monthly Downloads
- Admin Tools, Chat Related, Teleportation, Economy, and General
- 130,285 Monthly Downloads
- World Editing and Management and Admin Tools
- 93,898 Monthly Downloads
- General, Mechanics, Forge, and Items and Blocks
- 90,146 Monthly Downloads
- Thermal Expansion
- Fun, General, Items and Blocks, Mechanics, and Forge
- 69,202 Monthly Downloads