DĂ©veloppeur API

HyperPerms fournit un Java API pour les développeurs de plugins afin de vérifier les permissions, gérer les groupes, et s'intégrer au système de permission de manière programmatique.

Pour commencer

Ajouter la dépendance

Ajoutez HyperPerms comme dépendance dans votre projet :

Maven

<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

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

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

DĂ©pendance du plugin

Ajoutez HyperPerms comme dépendance dans votre plugin.yml :

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

Accéder au API

Obtenir l'instance API

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!");
    }
}

VĂ©rification des autorisations

ContrĂ´le de base des permissions

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);
}

ContrĂ´le des autorisations avec contexte

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);
}

Obtenir la valeur de la permission

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());
}

Gestion des groupes

Obtenir des groupes de joueurs

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();
}

Modifier les groupes de joueurs

// 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);
    }
}

Travailler avec des groupes

// 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;
}

Ajouter et supprimer des permissions

Permissions de l'utilisateur

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);
    }
}

Permissions de groupe

// 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);
    }
}

Travailler avec des pistes

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);
}

Préfixe et suffixe

// 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();
}

Meilleures pratiques

Mise en cache

Tip: HyperPerms met en cache les résultats des permissions en interne. Vous n'avez pas besoin d'implémenter votre propre cache pour les contrôles de permission.

Opérations asynchrones

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

Gestion des erreurs

// 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;
}

Voir aussi