API Cookbook

Short recipes for common integration tasks. For full method signatures, see Javadoc.

Setup

import ru.tehkode.permissions.bukkit.PermissionsEx;

if (!PermissionsEx.isAvailable()) {
    getLogger().warning("PEX not loaded");
    return;
}
var api = PermissionsEx.getApi();

Maven (provided scope):

<dependency>
  <groupId>dev.rono.permissions</groupId>
  <artifactId>permissionsex-api</artifactId>
  <version>1.23.5</version>
  <scope>provided</scope>
</dependency>

Check a permission

var user = api.getUserManager().getUser(player.getUniqueId());
if (user.has("myplugin.use")) {
    // allowed
}

Javadoc: User · PermissionSubject.has()

Add a permission to a user

var user = api.getUserManager().getUser(player.getUniqueId());
user.addPermission("myplugin.reward");
user.save();

Always call save() after mutations.

Javadoc: User.addPermission()

Add a permission to a group

var group = api.getGroupManager().getGroup("vip");
group.addPermission("essentials.fly");
group.save();

Javadoc: GroupManager · Group

Create a group

var group = api.getGroupManager().createGroup("vip");
group.addParent("default");
group.addPermission("essentials.fly");
group.setPrefix("&6[VIP] ");
group.save();

Javadoc: GroupManager.createGroup()

Add a user to a group

var user = api.getUserManager().getUser(player.getUniqueId());
user.addGroup("vip");
user.save();

Replace all groups:

user.setGroups(java.util.List.of("admin"));
user.save();

Javadoc: User.addGroup()

Timed permission

user.addTimedPermission("essentials.fly", 604800); // 7 days in seconds
user.save();

Javadoc: PermissionSubject.addTimedPermission()

World-scoped permissions

import dev.rono.permissions.api.permission.PermissionContext;

var ctx = PermissionContext.of(player.getWorld().getName());
var scoped = user.inContext(ctx);
if (scoped.has("myplugin.nether-only")) {
    // ...
}
scoped.addPermission("myplugin.visited");
user.save();

Javadoc: PermissionContext · SubjectContext

Promote / demote

try {
    user.promote("staff");
} catch (RankingException e) {
    getLogger().warning("Cannot promote: " + e.getMessage());
}

Javadoc: User.promote()

Listen for changes (Spigot)

Legacy Bukkit events — still the recommended way on game servers:

import ru.tehkode.permissions.events.PermissionEntityEvent;
import org.bukkit.event.EventHandler;

@EventHandler
public void onChange(PermissionEntityEvent event) {
    getLogger().info("Changed: " + event.getIdentifier());
}

Modern event bus:

api.events().subscribe(dispatch -> {
    getLogger().info("Dispatch: " + dispatch);
});

Javadoc: PermissionEntityEvent · PermissionsExApi.events()

Legacy API (existing plugins)

import ru.tehkode.permissions.PermissionUser;
import ru.tehkode.permissions.bukkit.PermissionsEx;

PermissionUser user = PermissionsEx.getUser(player);
boolean ok = PermissionsEx.getPermissionManager()
    .has(player, "myplugin.use", player.getWorld().getName());

Javadoc: PermissionManager · PermissionUser

Which API?

Situation	API
New plugin	Modern — `PermissionsEx.getApi()`
Existing PEX 1.23.x plugin	Legacy — usually works without changes
Bukkit events on Spigot	Legacy events
Bungee/Velocity proxy	`dev.rono.permissions.bungee.PermissionsEx.getApi()`

Full class reference: Javadoc

Sample plugins: GitHub /plugin