Pages

Upcoming Release Notes

1.3

The UUID update.

Developed against Bukkit 1.7.8+. May work with 1.7.5, but not recommended. Will definitely not work with anything lower.

If you use Vault, you must use Vault 1.4.x+

Requires Java 7+

Migration Procedure

Your data WILL be automatically migrated. However, it is recommended you do the following before running the new version.

(You may want to try this procedure out on a test server and test database first, using zPermission tables copied from production.)

  1. (Optional, but highly recommended) Back up your zPermissions database or the zPermissions data.yml depending on which storage option you're using. See your database server docs for the specifics. Note that once your database schema has been upgraded to the 1.3 version, you will not be able to easily run version 1.2 (should you need to). So again, this step is highly recommended.
  2. With your server on the old version of zPermissions (1.1.1, 1.2), issue the command: /perm export <filename> <filename> can be anything, e.g. uuid-backup.txt or whatever.

Once done, shut down your server, switch to the new version of zPermissions, and start it up again. zPermissions will automatically migrate any existing players. Keep an eye on the server log while it is doing so — if a player's UUID cannot be determined after querying Mojang's servers, they will be deleted.

If anything should go horribly wrong (e.g. network problems while querying Mojang's servers), restore from database backup (or data.yml backup) and try again.

Alternatively, switch to an older version of zPermissions, run /perm purge, switch back to a new version, and then attempt to /perm import the backup export you made above.

Sample Migration Log

[zPermissions] 150 entities to migrate
[zPermissions] 499 memberships to migrate
[zPermissions] Looking up 449 UUIDs...
[zPermissions] Migrating entities...
[zPermissions] Unable to migrate 'xxx' -- failed to lookup UUID
[zPermissions] Migrating memberships...
[zPermissions] Unable to migrate 'yyy' (member of 'resident') -- failed to lookup UUID
[zPermissions] Unable to migrate 'zzz' (member of 'resident') -- failed to lookup UUID
[zPermissions] Deleting entities that failed to migrate...
[zPermissions] Deleting memberships that failed to migrate...
[zPermissions] Migration done

UUID Notes

  • The name column in the entities table will now hold the 16-byte hex representation of a player's UUID. The display_name column will continue to hold the player's name, but it will only be used for display in order to avoid a reverse-UUID lookup.

  • The memberships table adds a display_name column, serving the same purpose as above.

  • The member column in the memberships table will now hold the hex UUID of the player.

  • When a player logs in, the display_name columns in both of these tables are updated with their current name, if different.

  • All commands that accept a player name will now also accept a UUID in four forms:

    • ef046b514ef44e15bb1a3d21f9da0ebc
    • ef046b51-4ef4-4e15-bb1a-3d21f9da0ebc
    • ef046b514ef44e15bb1a3d21f9da0ebc/ZerothAngel
    • ef046b51-4ef4-4e15-bb1a-3d21f9da0ebc/ZerothAngel

    The latter two are for (temporarily) setting their display name. (Remember, their display name is updated whenever they log in, so it's just there for your convenience.) If you don't set a display name and they aren't online, it will simply set it to the same as their UUID.

  • The /perm export command will now always export commands using UUID.

  • All commands that accept a player name will do the following:

    1. If it is already a UUID (one of the above forms), then use that
    2. If the named player is online, use their UUID
    3. Check the (zPerms) UUID cache. If found, use that. Note that the cache is controlled by two hidden options: uuid-cache-size and uuid-cache-ttl which default to 1000 and 120 (minutes) respectively.
    4. Otherwise, perform a (possibly remote) lookup. Since this has the potential to block the main thread, it will be done in the background. This means that if a lookup is performed, the command will return right away but you may not get the results until some time later.

  • Commands that display lists of players — /perm list, /perm search, /perm group ... members — will accept a new option: -U or --uuid. With this option, the players will be displayed as "UUID/LastKnownName"

  • The native zPermissions API (ZPermissionsService) has added new methods that take and return UUIDs for anything that involves players. The old player-related methods have been deprecated, and simply map usernames to UUIDs by using Bukkit.getOfflinePlayer(String). Note that in Bukkit 1.7.8+, this is now a potentially blocking method.

  • The VaultAPI implementation included with zPermissions natively supports all the OfflinePlayer-based versions of VaultAPI methods. Note that VaultAPI methods based on player name (which are now deprecated) will map usernames to OfflinePlayers using Bukkit.getOfflinePlayer(String), a potentially blocking method in Bukkit 1.7.8+. Plugins are advised to switch to the new OfflinePlayer-based methods.

Breaking Changes

  • The player..rename command has been removed for obvious reasons. The player..clone command remains.
  • For the /perm diff command: the <player> and <other-player> arguments no longer take "qualified" player names (e.g. qualified by world). Instead, the command takes an explicit -w or -W option to specify the world for <player> and/or <other-player> respectively.

Other Changes Since 1.2

  • Minor changes to error handling during startup, now a bit more comprehensive.
  • Make log-vault-changes default to false.

Changes Since 1.3beta1

  • Pre-load UuidResolver cache after player logs out.
  • Do not attempt to update display names when in read-only mode.
  • Properly delete failed migrations of temporary memberships for flat-files.
  • Fix bug where OP players would not have permissions during PlayerLoginEvent.
  • Add -A/--add-no-reset option to membership commands so that existing permanent memberships are left untouched.
  • Move prefix/suffix chat logic out of Vault and into ZPermissionService.
  • Add service-metadata-prefix-hack option so plugins written directly against ZPermissionsService (e.g. EssentialsChat) can take advantage of new prefix/suffix chat logic.
  • Switch to VaultAPI, directly implement all OfflinePlayer-based methods.
  • Display less-verbose permissions error messages based on the zpermissions.error.detail permission (true by default).
  • Switch to Java 7.
  • Raise UUID cache defaults to 1000 entries and 2 hours.
  • Allow world mirroring to use glob-style matching of world names.
  • Add custom-storage-strategy option to allow for alternate StorageStrategy implementations.
  • Add first-level UUID cache to database storage strategy which simply caches into a separate table.
  • Add hidden commands to invalidate the UUID resolver's cache.
  • Add explicit-default-group-membership option to explicitly add players to the default group if they aren't in any groups upon login.
  • Add region support for Factoid.