Skip to content

Releases: HyperSystemsDev/HyperPerms

v2.7.8 - API v2 Foundation & PlaceholderAPI Integration

05 Feb 13:17
@ZenithDevHQ ZenithDevHQ
v2.7.8
5866606

Choose a tag to compare

View all tags
v2.7.8 - API v2 Foundation & PlaceholderAPI Integration Latest
Latest

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

Placeholder Description
%hyperperms_prefix% Player's prefix
%hyperperms_suffix% Player's suffix
%hyperperms_group% Primary group name
%hyperperms_groups% All groups (comma-separated)
%hyperperms_group_weight% Primary group weight
%hyperperms_has_<permission>% Check if player has permission

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

Upgrade Notes

  • Drop-in replacement for v2.7.7
  • No configuration changes required
  • All API v2 additions are backwards compatible
  • Existing event subscriptions continue to work

Breaking Changes

None. All changes are additive and backwards compatible.

Full Changelog: v2.7.7...v2.7.8

Discord: https://discord.gg/SNPjyfkYPc

Assets 3
Loading

v2.7.7 - Permission Templates, Analytics, Optional SQLite

05 Feb 03:19
@ZenithDevHQ ZenithDevHQ
v2.7.7
7bceaa0

Choose a tag to compare

View all tags
v2.7.7 - Permission Templates, Analytics, Optional SQLite

Overview

Major feature release introducing the Permission Templates system, Analytics & Auditing, and significant JAR size reduction through optional SQLite.

Highlights

  • Permission Templates: 11 pre-built server configurations (factions, survival, skyblock, etc.)
  • Analytics System: Track permission usage, view hotspots, audit change history
  • 84% Smaller JAR: Reduced from ~15MB to ~2.4MB with optional SQLite
  • Console Improvements: Clickable hyperlinks in supported terminals

New Features

Permission Templates

Quickly set up your server with pre-built role configurations:

/hp template list                    # View available templates
/hp template preview <name>          # Preview before applying
/hp template apply <name>            # Apply a template
/hp template export <name>           # Export current setup as template

11 Built-in Templates:

Template Description
factions Faction wars server with claiming and raiding
survival Standard survival multiplayer
creative Creative building server
minigames Minigames and arcade server
smp Small community SMP
skyblock Skyblock gameplay
prison Prison server with ranks
rpg RPG/adventure server
towny Town-based survival
vanilla Near-vanilla experience
staff Staff roles (admin, mod, helper)

Custom Templates: Create your own by placing JSON files in the templates/ folder.

Analytics System

Track permission usage and audit changes (requires SQLite):

/hp analytics summary                # Overview of permission health
/hp analytics hotspots [limit]       # Most frequently checked permissions
/hp analytics unused [days]          # Permissions not checked recently
/hp analytics audit [holder]         # Permission change history
/hp analytics export [format]        # Export to JSON or CSV

Enable in config:

{
  "analytics": {
    "enabled": true,
    "trackChecks": true,
    "trackChanges": true,
    "retentionDays": 90
  }
}

Console Clickable Links

Modern terminals now support clickable hyperlinks:

  • Web editor URLs are clickable in iTerm2, Windows Terminal, GNOME Terminal, and more
  • Automatic detection of supported terminals
  • Fallback to plain URLs for unsupported terminals

Optional SQLite Driver

SQLite is no longer bundled to reduce JAR size:

  • Before: ~15MB (native libraries for 20+ platforms)
  • After: ~2.4MB (84% reduction)

To enable SQLite features:

  1. Download from sqlite-jdbc releases
  2. Place in mods/com.hyperperms_HyperPerms/lib/
  3. Restart server

Without SQLite: Everything works - analytics disabled, JSON storage used.

Installation

  1. Download HyperPerms-2.7.7.jar from this release
  2. Place in your server's mods folder
  3. Start the server

Quick Setup with Templates

/hp template apply staff             # Set up admin/mod/helper groups
/hp template apply survival          # Add survival gameplay permissions
/hp user YourName parent add admin   # Make yourself admin

Technical Changes

v2.7.7

  • SQLiteDriverLoader utility for dynamic driver loading
  • Analytics commands show clickable download links when driver missing
  • Changed sqlite-jdbc to compileOnly (not bundled)
  • Removed slf4j-nop dependency
  • Redesigned README with screenshot and wiki link

v2.7.6

  • Removed Class.forName fallback for CurseForge compliance
  • H2 migration loads driver exclusively from LuckPerms libs

v2.7.5

  • Permission Templates system with 11 bundled templates
  • Analytics system with SQLite storage
  • Console hyperlink support (OSC8)
  • Config version migrations

Requirements

  • Hytale Early Access
  • Java 25 (Temurin recommended)

Links

Loading

v2.7.4 - Cloudflare Workers API Migration

04 Feb 11:37
@ZenithDevHQ ZenithDevHQ
v2.7.4
34a7b28

Choose a tag to compare

View all tags
v2.7.4 - Cloudflare Workers API Migration

Cloudflare Workers API Migration

This release introduces a major infrastructure improvement that routes game server API traffic through Cloudflare Workers, significantly reducing Vercel function invocations and costs.

What's New

Hybrid API Architecture

HyperPerms now uses a split architecture for better performance and cost efficiency:

Traffic Type Endpoint Provider
Game Server API api.hyperperms.com Cloudflare Workers
Web Editor UI www.hyperperms.com Vercel

Both endpoints share the same Redis database, ensuring seamless data consistency.

New Configuration Option

A new apiUrl option has been added to the webEditor config section:

{
  "webEditor": {
    "url": "https://www.hyperperms.com",
    "apiUrl": "https://api.hyperperms.com",
    "timeoutSeconds": 10
  }
}

Automatic Config Migration

No manual configuration required! When you upgrade to v2.7.4, the plugin automatically:

  1. Detects missing apiUrl field
  2. Adds it with the default Cloudflare Workers endpoint
  3. Saves the updated config

You'll see this log message on first startup:

[HyperPerms] Config migration: Added webEditor.apiUrl (Cloudflare Workers API endpoint)

Technical Details

Plugin Changes

  • Added getWebEditorApiUrl() method with fallback to main URL
  • createSession() now uses apiUrl for API calls
  • fetchChanges() now uses apiUrl for API calls
  • Browser URLs in responses still use the main url setting

Backward Compatibility

  • Older configs without apiUrl continue to work (auto-migrated on load)
  • If apiUrl is empty or removed, plugin falls back to main url
  • No breaking changes to commands or permissions

Upgrade Notes

  • Drop-in replacement for v2.7.3
  • No manual config changes needed - auto-migration handles it
  • Fully backward compatible

Full Changelog: v2.7.3...v2.7.4

Discord: https://discord.gg/SNPjyfkYPc

Loading

v2.7.3 - Performance Fix & LuckPerms H2 Migration

03 Feb 21:29
@ZenithDevHQ ZenithDevHQ
v2.7.3
3a5d7c2

Choose a tag to compare

View all tags
v2.7.3 - Performance Fix & LuckPerms H2 Migration

Performance Fix & LuckPerms H2 Migration

This release includes a critical performance fix and completes LuckPerms H2 database migration support.

Performance Fix

Cache Bypass Fix in Permission Checks

Fixed a critical performance issue where HyperPermsPermissionSet.contains() was bypassing the Caffeine permission cache, triggering a full permission resolution on every call. This was consuming 6.5% CPU in profiling.

Technical Details:

  • Added checkPermission() method to HyperPerms that returns TriState and properly uses the cache
  • Refactored HyperPermsPermissionSet.contains() to use the cached lookup instead of calling resolver directly
  • Removed redundant getOrLoadUser() private method

Performance Impact:

  • Before: Every contains() call triggered full resolve() - O(n groups * m nodes)
  • After: Cache hit = O(1) lookup; cache miss = resolve + cache store
  • Expected 90%+ reduction in CPU time for permission checks

LuckPerms H2 Migration Support

Command Syntax Update

Due to Hytale command framework limitations, migration options now use dash-separated syntax:

/hp migrate luckperms-confirm-verbose

H2 Database Reader Enhancements

  • Dynamically loads H2 driver from LuckPerms libs/ folder for version compatibility
  • Handles locked databases by creating temporary copies
  • Fixed connection URL to use absolute paths (required by H2 2.1.x+)
  • Set thread context classloader for proper class isolation
  • H2 is now compileOnly to avoid version conflicts with bundled driver

Storage Detection Improvements

  • Fixed path resolution to correctly find LuckPerms in /mods/ folder
  • Case-insensitive folder name detection (finds LuckPerms_LuckPerms, etc.)
  • Flexible pattern matching for database files
  • Support for various LuckPerms folder naming conventions

Windows Support

  • Added clear error message for Windows file locking issues
  • Users are directed to stop LuckPerms before migrating when database is locked

Upgrade Notes

  • Drop-in replacement for v2.7.0
  • No configuration changes required
  • Fully backwards compatible

Full Changelog: v2.7.0...v2.7.3

Discord: https://discord.gg/SNPjyfkYPc

Loading

v2.7.0: Track Promote/Demote & Update Command Fix

02 Feb 14:16
@ZenithDevHQ ZenithDevHQ
v2.7.0
cf0fdbd

Choose a tag to compare

View all tags
v2.7.0: Track Promote/Demote & Update Command Fix

New Features

Track-Based Promote/Demote Commands

Easily manage user progression through rank tracks with two new commands:

/hp user promote <player> <track>

  • Promotes a user to the next rank on the specified track
  • If the user is not on the track, adds them to the first group
  • Shows informative message if user is already at the top
  • Handles all edge cases gracefully

/hp user demote <player> <track>

  • Demotes a user to the previous rank on the specified track
  • Shows error if user is not currently on the track
  • Shows informative message if user is already at the bottom
  • Handles all edge cases gracefully

Example Usage

# Promote a player through the staff track
/hp user promote PlayerName staff

# Demote a player on the staff track
/hp user demote PlayerName staff

Bug Fixes

Fixed /hp update confirm Command

  • Issue: Running /hp update confirm threw an "expected 0, given 1" argument error
  • Root Cause: The command framework validated arguments before execution, rejecting "confirm" because no argument descriptor existed
  • Solution: Refactored to use the nested subcommand pattern, properly registering confirm as a subcommand of update

Permissions

Command Permission
/hp user promote hyperperms.command.user.promote
/hp user demote hyperperms.command.user.demote

Full Changelog: v2.6.0...v2.7.0

Loading

v2.6.0: HyperFactions Integration

01 Feb 14:26
@ZenithDevHQ ZenithDevHQ
v2.6.0
9a8614e

Choose a tag to compare

View all tags
v2.6.0: HyperFactions Integration

New Features

HyperFactions Integration

  • Added built-in support for HyperFactions permission integration
  • Seamless permission checking between HyperPerms and HyperFactions
  • Automatic permission provider registration when HyperFactions is detected

Bug Fixes

  • Permission Set Checks: Fixed an issue where user data wasn't properly loaded during permission set validation
  • Improved reliability of permission checks during early player connection

Compatibility

  • Fully compatible with HyperFactions v0.3.2+
  • Backward compatible with existing permission configurations

Full Changelog: v2.5.1...v2.6.0

Loading

v2.5.1: Hytale-Native Permission Resolution

31 Jan 15:59
@ZenithDevHQ ZenithDevHQ
v2.5.1
902da80

Choose a tag to compare

View all tags
v2.5.1: Hytale-Native Permission Resolution

Changes

Permission Resolution Fix

  • Aligned permission resolution order with Hytale's native implementation
  • Global wildcard (*) is now checked first, matching Hytale's behavior
  • Prefix wildcards now resolve shortest-first (a.* before a.b.*)

Bug Fixes

  • Fixed user not being loaded during permission set checks, which could cause negation checks to fail
  • Fixed runtime permission discovery not finding the plugins directory

Upgrade Notes

This release changes how permissions are resolved to match Hytale's native order. If you previously relied on negations overriding global wildcards (e.g., ["*", "-admin.dangerous"]), note that the global * will now win.

To deny specific permissions while granting most others, use specific wildcards instead of global *:

permissions:
  - "admin.*"
  - "-admin.dangerous"  # This still works

Download

Download HyperPerms-2.5.1.jar below and place it in your mods folder.

Loading

v2.5.0: Runtime Permission Discovery, Update Notifications & LuckPerms Migration

30 Jan 22:44
@ZenithDevHQ ZenithDevHQ
v2.5.0
3388865

Choose a tag to compare

View all tags
v2.5.0: Runtime Permission Discovery, Update Notifications & LuckPerms Migration

Runtime Permission Discovery, Update Notifications & LuckPerms Migration

This is a massive update introducing intelligent runtime permission discovery, automatic update notifications, and a complete LuckPerms migration tool.

Runtime Permission Discovery

HyperPerms now automatically discovers and registers permissions from all installed plugins, making them instantly available in the web editor without manual configuration.

How It Works

JAR Scanning at Startup

  • Scans plugin JAR files for permission strings in bytecode
  • Extracts plugin names from manifest.json
  • Builds namespace-to-plugin mappings (e.g., "theeconomy" -> "EconomySystem")
  • Pre-registers permissions so they appear immediately in the web editor

Intelligent Filtering

  • Blacklist of 50+ code-related words to prevent false positives
  • Known permission prefix whitelist
  • Pattern validation (2-5 segments, 3+ char namespace)
  • Java package rejection (java., javax., org., com.google., etc.)

Performance

  • Results cached in jar-scan-cache.json
  • Cache keyed by JAR filename and modification timestamp
  • Unchanged JARs skipped on subsequent startups
  • Typical overhead: 1-3 seconds initial scan, near-zero for cached

Web Editor Integration

The web editor now displays discovered permissions with full context:

  • "Installed" badges appear next to permissions from running plugins
  • Dynamic categories created for each discovered plugin
  • Seamless merge with the static permission registry
  • Makes finding the right permissions faster and easier

Operator Update Notification System

Never miss an update. Operators automatically receive notifications when joining the server.

Commands:

  • /hp update - Check for available updates
  • /hp update confirm - Download update to mods folder
  • /hp updates - View notification preference
  • /hp updates on|off - Toggle join notifications

Features:

  • Delayed notification (1.5s after join) for clean UX
  • Opt-out model (enabled by default)
  • Preferences persist in notification-preferences.json
  • GitHub release version checking

LuckPerms Migration Tool

Migrate from LuckPerms to HyperPerms with a single command.

Commands:

  • /hp migrate luckperms - Preview migration (dry-run)
  • /hp migrate luckperms --confirm - Execute migration
  • /hp migrate luckperms --verbose - Detailed preview
  • Conflict resolution: --merge (default), --skip, --overwrite

Supported Storage Backends:

  • YAML file storage
  • JSON file storage
  • H2 embedded database
  • MySQL/MariaDB remote database

What Gets Migrated:

  • Groups with weights, prefixes, suffixes
  • All user permissions and group memberships
  • Tracks/ladders with correct ordering
  • Temporary permissions with expiry
  • Context mappings (server, world)
  • Group inheritance hierarchies

Safety:

  • Automatic backup before migration
  • Dry-run mode by default
  • Full rollback on failure
  • Circular inheritance detection

Compatibility Fixes

Hex Color Support and Werchat Compatibility

  • Added hex color parsing (§x§R§R§G§G§B§B format)
  • Added underline and strikethrough format codes
  • Werchat detection: HyperPerms defers chat handling when Werchat is installed
  • New ChatAPI.getRawPrefix() and getRawSuffix() methods

HyperPerms + HyFactions Chat Fix

  • Resolved chat prefix conflict when both plugins are installed
  • Dynamic event priority based on HyFactions presence
  • Output: [FactionTag] [RankPrefix] PlayerName: message

Player List Formatting

  • Complete rewrite using Hytale's packet system
  • Proper async prefix/suffix resolution
  • Strip color codes and invisible Unicode characters
  • Add left padding to prevent UI clipping

Startup Error Fixes

  • Null-safe server root resolution in LuckPerms migrator
  • Removed verbose debug logging spam

Permission System Fixes

Universal Permission Negation Fix

Restructured WildcardMatcher.check() to properly evaluate negations before grants. Previously, grants like com.hyperwarps.* would return TRUE before negations were evaluated.

User Permission Leak Fix

Fixed PermissionProvider.addUserPermissions() which was incorrectly persisting every permission check as a direct user node.

Security Fix

Removed overly broad com.* from HyperHomes built-in permissions.

Expanded Wildcard Aliases

  • HyperHomes: Added share, admin, and bypass wildcard expansions
  • HyperWarps: Full wildcard expansion with bypass permissions

Web Editor Updates (HyperPermsWeb)

Dynamic Permission Discovery Support

  • Backend plugin permissions displayed in web editor
  • "Installed" badges for permissions from running plugins
  • Dynamic categories for discovered plugins

Negative Permission Support

  • Proper parsing of denied permissions (-permission.node)
  • Red text and - prefix in UI for denied permissions

Bug Fixes

  • Fixed manual permission input disappearing after one character
  • Fixed old JSON config compatibility
  • Fixed CSRF validation blocking production requests
  • Fixed i18n namespace issues

Test Coverage

Added P0 specification verification tests covering:

  • User negation overrides group grant
  • Specific negation with wildcard
  • Context-specific overrides global
  • Expired permission handling
  • Default group fallback
  • Weight priority conflicts

All 118 tests pass.

Upgrade Notes

  • Drop-in replacement for v2.4.5
  • No configuration changes required
  • All new features work automatically
  • Fully backwards compatible

Full Changelog: v2.4.5...v2.5.0

Discord: https://discord.gg/SNPjyfkYPc

Loading

v2.4.5: VaultUnlocked Integration & Dynamic Permission Support

26 Jan 01:26
@ZenithDevHQ ZenithDevHQ
v2.4.5
725c390

Choose a tag to compare

View all tags
v2.4.5: VaultUnlocked Integration & Dynamic Permission Support

VaultUnlocked Integration & Dynamic Permission Support

This is a major update that makes HyperPerms the first Hytale permission plugin with full VaultUnlocked support, enabling seamless compatibility with any Vault-aware plugin.

Highlights

VaultUnlocked Integration (NEW)

HyperPerms now automatically registers as a VaultUnlocked permission provider. Any plugin that uses VaultUnlocked for permissions will now work seamlessly with HyperPerms.

Supported Operations:

  • Permission checks (has, hasAsync)
  • Group membership (getGroups, inGroup, primaryGroup)
  • Group operations (addGroup, removeGroup)
  • Permission modification (setPermission, groupSetPermission)
  • Copy operations (copyPermissions, copyGroups)
  • Context-aware permission resolution

Zero Configuration Required! Simply install both HyperPerms and VaultUnlocked - the integration happens automatically.

Dynamic Permission Support (NEW)

The web editor now supports dynamic permission detection. When you connect your server:

  • "Installed" badges appear next to permissions from plugins running on your server
  • Permissions are automatically scanned from registered plugins
  • Merges seamlessly with the static permission registry
  • Makes finding the right permissions faster and easier

HyperFactions & HyperHomes Permission Registry

Added 31+ pre-registered permissions for HyperSystems plugins:

HyperFactions (14 permissions):

  • hyperfactions.*, .use, .create, .admin
  • .rename, .desc, .color, .open, .close
  • .bypass.*, .bypass.build, .bypass.interact, .bypass.cooldown, .bypass.warmup

HyperHomes (17 permissions):

  • hyperhomes.*, .use, .set, .delete, .list, .share, .gui, .unlimited
  • .bypass.*, .bypass.warmup, .bypass.cooldown
  • .admin.*, .admin, .admin.reload, .admin.update, .admin.migrate, .admin.teleport.others

Bug Fixes & Improvements

  • Fixed optional dependency format for Hytale's plugin loader
  • Added comprehensive debug logging for Vault operations (enable with /hp debug)
  • Improved transient permission handling (graceful fallback instead of errors)
  • Enhanced cache invalidation after Vault-based modifications

Documentation

Full documentation available at hyperperms.com/wiki:

  • VaultUnlocked integration guide
  • Permission autofill guide
  • Available in English, German, and French

Technical Details

New Files:

  • VaultUnlockedIntegration.java - Soft dependency detection & lifecycle
  • HyperPermsVaultProvider.java - Full PermissionUnlocked implementation (~500 lines)
  • PluginPermissionScanner.java - Dynamic permission discovery
  • PluginPermissions.java - Permission data transfer object

Configuration:

vault:
  enabled: true  # Disable if needed

Upgrade Notes

  • Drop-in replacement for v2.4.3
  • No configuration changes required
  • VaultUnlocked integration is automatic when both plugins are present
  • Fully backwards compatible

Full Changelog: v2.4.3...v2.4.5

Discord: https://discord.gg/SNPjyfkYPc

Loading

v2.4.3: Hytale Permission Discovery & Major Bug Fixes

24 Jan 14:09
@ZenithDevHQ ZenithDevHQ
v2.4.3
53fdad2

Choose a tag to compare

View all tags
v2.4.3: Hytale Permission Discovery & Major Bug Fixes

What's Changed

This is a major release with extensive bug fixes, a complete permission aliasing overhaul, and comprehensive documentation. We discovered how Hytale actually checks permissions and rebuilt our alias system to match.

Hytale Permission Discovery

After decompiling HytaleServer.jar, we discovered the actual permission nodes Hytale checks. This was the root cause of permissions not working correctly.

The Discovery

Hytale uses a .self/.other suffix pattern for player-targeted commands:

What We Thought What Hytale Actually Checks
hytale.command.player.gamemode hytale.command.gamemode.self, hytale.command.gamemode.other
hytale.command.player.kill hytale.command.kill.self, hytale.command.kill.other
hytale.command.player.teleport hytale.command.teleport.self, hytale.command.teleport.other

How It's Fixed

Web UI permissions now correctly expand to actual Hytale permission nodes:

  • hytale.command.player.gamemode → grants both .gamemode.self and .gamemode.other
  • Same pattern applies to: kill, give, damage, spawn, whereami, refer, effects

New Features

Comprehensive Permission Aliasing System

  • ~100+ new permission mappings between web UI and actual Hytale nodes
  • Legacy hytale.system.command.* format support for older configs
  • Wildcard expansion now includes all actual Hytale permissions
  • Case-insensitive permission checking for Hytale compatibility

New Command Support

Warp Commands:

  • hytale.command.warp.go - Use warps
  • hytale.command.warp.set - Create warps
  • hytale.command.warp.remove - Delete warps
  • hytale.command.warp.list - List warps
  • hytale.command.warp.reload - Reload warp config

Inventory Commands:

  • hytale.command.invsee - View other player inventories
  • hytale.command.invsee.modify - Edit other player inventories
  • hytale.command.spawnitem - Spawn items directly

Teleport Sub-commands:

  • .teleport.all, .back, .forward, .top, .home, .world, .history

Editor Permissions

  • Preserved camelCase for hytale.editor.builderTools (case-sensitive!)
  • Full editor permission tree: brush, prefab, selection, packs, history

Documentation

  • Added HYTALE_PERMISSIONS.md - Complete reference of all actual Hytale permission nodes
  • Web UI to Hytale permission mapping tables
  • Wildcard expansion documentation
  • Verification/testing steps

Bug Fixes

Command System Overhaul

  • Refactored command help system with centralized formatting
  • Flag syntax for optional arguments: --name, --filename instead of positional args
  • Visual indicators: ✓, ✗, • for better UX
  • Replaced legacy color codes with Message API composition

Data Management & Safety

  • Confirmation steps for destructive commands (group deletion, user clearing, backup restoration)
  • Per-entity locking for concurrent user and group modifications
  • Cache invalidation now occurs after storage operations
  • Duplicate track prevention during concurrent creation
  • Exception logging in event handlers

Permission System Fixes

  • Alias expansion in getUserDirectPermissions() to match getExpandedPermissions() logic
  • Debug logging for alias expansion tracing
  • CaseInsensitiveSet for Hytale compatibility
  • Fixed /hp check command to use two required arguments
  • Fixed clearNodes() in user clear command to avoid UnsupportedOperationException

Default Groups

  • Cleaned up default-groups.json to use proper Hytale permission nodes

Files Changed

30 files modified with +3,095 / -689 lines

New Files

  • HYTALE_PERMISSIONS.md - Permission reference documentation
  • PermissionAliases.java - Centralized alias management (988 lines)
  • CaseInsensitiveSet.java - Hytale compatibility utility

Major Changes

  • HyperPermsCommand.java - Complete refactor (+800 lines)
  • PermissionRegistry.java - ~100 new permissions registered
  • PermissionResolver.java - Alias-aware permission checking
  • HyperPermsPermissionProvider.java - Alias expansion in provider

Upgrade Notes

This is a drop-in replacement. No configuration changes required.

After upgrading:

  1. Players with web UI permissions will have them correctly expanded to actual Hytale nodes
  2. Existing groups will work with the new alias system automatically
  3. Use /hyperperms verbose to see permission expansion in action

Technical Details

Permission Flow

  1. User assigned hytale.command.player.gamemode via web UI
  2. HyperPerms stores that permission
  3. On permission check, PermissionAliases.expand() adds:
    • hytale.command.gamemode.self
    • hytale.command.gamemode.other
  4. Hytale checks for hytale.command.gamemode.self - found in expanded set
  5. Command executes successfully

Commits Included

  • 530b645 - fix(aliases): sync permission aliases with actual Hytale permission nodes
  • e5cbf55 - fix(aliases): expand permission aliases in PermissionProvider
  • d454c32 - fix(commands): use flag syntax for optional args
  • 892bd0c - fix: improves data management and command confirmations
  • 4867d25 - fix: a whole lot of bugs
  • 1d6a590 - fix: clean default groups to use proper hytale permissions
  • 219f413 - v2.4.3: Expanded permission aliasing and case-insensitive checks
  • cd4a636 - feat: Add comprehensive permission aliasing system
  • 408da5f - feat: completely refactor command help
  • 34f7f94 - fix: use clearNodes() to avoid UnsupportedOperationException

Full Changelog

v2.4.1...v2.4.3

Loading