API v2 Foundation & PlaceholderAPI Integration

This release introduces the HyperPerms API v2 foundation with a completely overhauled event system, async permission methods, query capabilities, and metrics tracking. It also adds PlaceholderAPI integration for Hytale.

API v2 Foundation

New Event System

The event system has been completely overhauled with proper event firing across all permission operations.

New Event Classes:

• GroupCreateEvent - Fired when a group is created (cancellable)
• GroupDeleteEvent - Fired when a group is deleted (cancellable)
• GroupModifyEvent - Fired when group properties change
• UserGroupChangeEvent - Fired when user group membership changes
• UserLoadEvent - Fired when user data is loaded
• UserUnloadEvent - Fired when user is unloaded from cache
• DataReloadEvent - Fired when data is reloaded
• TrackPromotionEvent - Fired on track promotion (cancellable)
• TrackDemotionEvent - Fired on track demotion (cancellable)

Event Enhancements:

• Cancellable interface for events that can be cancelled
• EventPriority enum (LOWEST, LOW, NORMAL, HIGH, HIGHEST, MONITOR)
• Async event subscription support
• PermissionHolderListener pattern for User/Group models

Async Permission Methods

New async methods for non-blocking permission checks:

// Async permission check
api.hasPermissionAsync(uuid, "permission.node")
   .thenAccept(result -> { });

// Async with TriState
api.getPermissionValueAsync(uuid, "permission.node")
   .thenAccept(tristate -> { });

// Fluent async builder
api.checkAsync(uuid)
   .permission("build.place")
   .inWorld("nether")
   .withGamemode("survival")
   .result()
   .thenAccept(canBuild -> { });

TriState Enum

New TriState enum for distinguishing between TRUE, FALSE, and UNDEFINED permission states:

TriState value = api.getPermissionValue(uuid, "some.permission");
if (value == TriState.UNDEFINED) {
    // Permission not explicitly set
}

QueryAPI

New API for searching and querying users and groups:

QueryAPI query = api.getQuery();

// Find users with a permission
query.findUsersWithPermission("admin.*").thenAccept(uuids -> { });

// Find users in a group
query.findUsersInGroup("moderator").thenAccept(uuids -> { });

// Fluent user queries
query.queryUsers()
    .withPermission("build.*")
    .inGroup("builder")
    .withContext("world", "creative")
    .limit(100)
    .execute();

// Group queries
query.queryGroups()
    .withWeightBetween(50, 100)
    .inheritsFrom("default")
    .execute();

MetricsAPI

New API for accessing permission check statistics and audit logs:

MetricsAPI metrics = api.getMetrics();
if (metrics != null) {
    // Cache statistics
    CacheStats cache = metrics.getCacheStats();
    double hitRate = metrics.getCacheHitRate();
    
    // Permission check stats
    PermissionCheckStats stats = metrics.getCheckStats();
    
    // Hotspot analysis
    metrics.getHotspots(10).thenAccept(hotspots -> {
        hotspots.forEach(h -> 
            System.out.println(h.permission() + ": " + h.checkCount())
        );
    });
    
    // Audit log
    metrics.getRecentAuditLog(50).thenAccept(entries -> { });
}

Bulk Operations

New bulk operations in UserManager and GroupManager:

// Load multiple users
userManager.loadUsers(uuidCollection).thenAccept(userMap -> { });

// Save multiple users
userManager.saveUsers(userCollection);

// Batch modify users
userManager.batchModify(uuids, user -> {
    user.addNode(Node.builder("new.permission").build());
});

// Get all known UUIDs
userManager.getAllKnownUUIDs().thenAccept(allUuids -> { });

PlaceholderAPI Integration

HyperPerms now integrates with PlaceholderAPI for Hytale, providing two-way placeholder support.

Available Placeholders

Configuration

placeholderapi:
  enabled: true
  parse-external: true  # Parse external PAPI placeholders in chat

Bug Fixes

Async Threading Fix

Fixed a critical threading issue where permission checks could cause race conditions when called from async contexts. Permission resolution now properly handles concurrent access.

Prefix/Suffix Priority Fix

Group weight is now correctly used as the default priority for prefix and suffix resolution. Previously, the priority could be incorrectly calculated in certain inheritance scenarios.

Web Editor Error Messaging

Improved error messaging when applying empty or invalid changes from the web editor. Users now receive clear feedback about what went wrong.

Documentation

• Redesigned README with expanded features and documentation links
• Added comprehensive API documentation links
• Improved getting started guide