Developer API

HyperPerms provides a Java API for plugin developers to check permissions, manage groups, and integrate with the permission system programmatically.

Getting Started

Adding the Dependency

Add HyperPerms as a dependency in your project:

Maven

xml
<dependency>
    <groupId>dev.hyperperms</groupId>
    <artifactId>hyperperms-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

<repositories>
    <repository>
        <id>hyperperms-repo</id>
        <url>https://repo.hyperperms.dev/releases</url>
    </repository>
</repositories>

Gradle

groovy
repositories {
    maven { url 'https://repo.hyperperms.dev/releases' }
}

dependencies {
    compileOnly 'dev.hyperperms:hyperperms-api:1.0.0'
}

Plugin Dependency

Add HyperPerms as a dependency in your plugin.yml:

yaml
name: MyPlugin
version: 1.0.0
main: com.example.MyPlugin
depend: [HyperPerms]

Accessing the API

Getting the API Instance

java
import dev.hyperperms.api.HyperPermsAPI;
import dev.hyperperms.api.HyperPermsProvider;

public class MyPlugin extends JavaPlugin {

    private HyperPermsAPI hyperPerms;

    @Override
    public void onEnable() {
        // Get the API instance
        hyperPerms = HyperPermsProvider.get();

        if (hyperPerms == null) {
            getLogger().severe("HyperPerms not found!");
            getServer().getPluginManager().disablePlugin(this);
            return;
        }

        getLogger().info("HyperPerms API loaded successfully!");
    }
}

Checking Permissions

Basic Permission Check

java
import dev.hyperperms.api.model.User;
import java.util.UUID;

// Check if a player has a permission
public boolean checkPermission(UUID playerUuid, String permission) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return false;
    }

    return user.hasPermission(permission);
}

Permission Check with Context

java
import dev.hyperperms.api.context.ContextSet;

// Check permission with specific context
public boolean checkPermissionInWorld(UUID playerUuid, String permission, String world) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return false;
    }

    ContextSet contexts = ContextSet.builder()
        .add("world", world)
        .build();

    return user.hasPermission(permission, contexts);
}

Getting Permission Value

java
import dev.hyperperms.api.model.PermissionResult;

// Get detailed permission result
public void checkPermissionDetail(UUID playerUuid, String permission) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return;
    }

    PermissionResult result = user.getPermissionValue(permission);

    System.out.println("Permission: " + permission);
    System.out.println("Value: " + result.getValue());
    System.out.println("Source: " + result.getSource());
    System.out.println("Is Set: " + result.isSet());
}

Managing Groups

Getting Player Groups

java
import dev.hyperperms.api.model.Group;
import java.util.Set;

// Get all groups a player belongs to
public Set<Group> getPlayerGroups(UUID playerUuid) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return Set.of();
    }

    return user.getGroups();
}

// Get primary group
public Group getPrimaryGroup(UUID playerUuid) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return null;
    }

    return user.getPrimaryGroup();
}

Modifying Player Groups

java
// Add player to a group
public void addToGroup(UUID playerUuid, String groupName) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);
    Group group = hyperPerms.getGroupManager().getGroup(groupName);

    if (user != null && group != null) {
        user.addGroup(group);
        hyperPerms.getUserManager().saveUser(user);
    }
}

// Remove player from a group
public void removeFromGroup(UUID playerUuid, String groupName) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);
    Group group = hyperPerms.getGroupManager().getGroup(groupName);

    if (user != null && group != null) {
        user.removeGroup(group);
        hyperPerms.getUserManager().saveUser(user);
    }
}

// Set primary group
public void setPrimaryGroup(UUID playerUuid, String groupName) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);
    Group group = hyperPerms.getGroupManager().getGroup(groupName);

    if (user != null && group != null) {
        user.setPrimaryGroup(group);
        hyperPerms.getUserManager().saveUser(user);
    }
}

Working with Groups

java
// Get a group by name
public Group getGroup(String name) {
    return hyperPerms.getGroupManager().getGroup(name);
}

// Get all groups
public Set<Group> getAllGroups() {
    return hyperPerms.getGroupManager().getGroups();
}

// Create a new group
public Group createGroup(String name) {
    return hyperPerms.getGroupManager().createGroup(name);
}

// Check if a group exists
public boolean groupExists(String name) {
    return hyperPerms.getGroupManager().getGroup(name) != null;
}

Adding and Removing Permissions

User Permissions

java
import dev.hyperperms.api.model.Node;

// Add a permission to a user
public void addUserPermission(UUID playerUuid, String permission, boolean value) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user != null) {
        Node node = Node.builder()
            .permission(permission)
            .value(value)
            .build();

        user.addPermission(node);
        hyperPerms.getUserManager().saveUser(user);
    }
}

// Remove a permission from a user
public void removeUserPermission(UUID playerUuid, String permission) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user != null) {
        user.removePermission(permission);
        hyperPerms.getUserManager().saveUser(user);
    }
}

Group Permissions

java
// Add a permission to a group
public void addGroupPermission(String groupName, String permission, boolean value) {
    Group group = hyperPerms.getGroupManager().getGroup(groupName);

    if (group != null) {
        Node node = Node.builder()
            .permission(permission)
            .value(value)
            .build();

        group.addPermission(node);
        hyperPerms.getGroupManager().saveGroup(group);
    }
}

// Add a contextual permission
public void addContextualPermission(String groupName, String permission, String world) {
    Group group = hyperPerms.getGroupManager().getGroup(groupName);

    if (group != null) {
        Node node = Node.builder()
            .permission(permission)
            .value(true)
            .context("world", world)
            .build();

        group.addPermission(node);
        hyperPerms.getGroupManager().saveGroup(group);
    }
}

Working with Tracks

java
import dev.hyperperms.api.model.Track;

// Get a track
public Track getTrack(String name) {
    return hyperPerms.getTrackManager().getTrack(name);
}

// Promote a player on a track
public boolean promotePlayer(UUID playerUuid, String trackName) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);
    Track track = hyperPerms.getTrackManager().getTrack(trackName);

    if (user == null || track == null) {
        return false;
    }

    return hyperPerms.getTrackManager().promote(user, track);
}

// Demote a player on a track
public boolean demotePlayer(UUID playerUuid, String trackName) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);
    Track track = hyperPerms.getTrackManager().getTrack(trackName);

    if (user == null || track == null) {
        return false;
    }

    return hyperPerms.getTrackManager().demote(user, track);
}

Prefix and Suffix

java
// Get player's effective prefix
public String getPlayerPrefix(UUID playerUuid) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return "";
    }

    return user.getPrefix();
}

// Get player's effective suffix
public String getPlayerSuffix(UUID playerUuid) {
    User user = hyperPerms.getUserManager().getUser(playerUuid);

    if (user == null) {
        return "";
    }

    return user.getSuffix();
}

Best Practices

Caching

HyperPerms caches permission results internally. You don't need to implement your own caching for permission checks.

Async Operations

java
// For bulk operations, use async methods
hyperPerms.getUserManager().loadUser(playerUuid).thenAccept(user -> {
    // Process user data
    user.addGroup(someGroup);
    hyperPerms.getUserManager().saveUser(user);
});

Error Handling

java
// Always check for null returns
User user = hyperPerms.getUserManager().getUser(playerUuid);
if (user == null) {
    // User hasn't joined before or data isn't loaded
    return;
}

Group group = hyperPerms.getGroupManager().getGroup("vip");
if (group == null) {
    // Group doesn't exist
    getLogger().warning("VIP group not found!");
    return;
}

See Also