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.

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

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

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

v2.4.1 - User Data Persistence Fix

What's Changed

Critical Bug Fix: Player Group Assignments Preserved on Restart

Fixed a critical issue where player-to-group assignments were lost after server restart, while group permissions themselves were preserved. This caused all players (including owners) to lose their assigned groups.

Root Cause

• User data was never loaded during server startup - only groups and tracks were loaded
• A race condition existed between loadUser() and getOrCreateUser() that could overwrite loaded user data
• Fire-and-forget async saves could be lost during quick server shutdowns

Fixes Applied

1. Load All Users on Startup

• Added userManager.loadAll().join() during server initialization
• Ensures all user data is loaded from storage when the server starts

2. Race Condition Prevention

• Modified loadUser() to use atomic compute() operations
• Prevents newly-created default users from overwriting loaded user data
• Only overwrites existing users if they still have the default group

3. Synchronous Critical Saves

• Changed all critical saveUser() calls to await completion with .join()
• Prevents data loss during rapid server shutdowns
• Affects: setPrimaryGroup, addGroup, removeGroup, setPermission, removePermission, setPrefix, setSuffix, and clear commands

Files Modified

• HyperPerms.java - Added user loading on startup
• UserManagerImpl.java - Fixed race condition in loadUser()
• HyperPermsCommand.java - Awaited critical save operations

Upgrade Notes

This is a drop-in replacement. No configuration changes required. After upgrading, all player group assignments will persist correctly across server restarts.

v2.3.5

What's Changed

HyperHomes Integration

• Added permission aliasing for HyperHomes plugin
• hyperhomes.gui now properly maps to com.hyperhomes.hyperhomes.command.homes.gui
• hyperhomes.use grants access to main home commands
• Wildcard hyperhomes.* expands to all HyperHomes permissions

Hytale PermissionProvider Fixes

• Fixed user permissions not being recognized by Hytale's built-in system
• Added virtual user group mechanism for direct user permissions
• Proper wildcard expansion at all hierarchy levels
• Full group inheritance chain resolution

Other Changes

• Added TabList cache invalidation
• Cleaned up debug logging
• Performance improvements to permission resolution

v2.3.4 - ChatAPI Prefix Fix

What's Fixed

This release fixes a critical regression where prefixes were returning empty strings for external plugins using the ChatAPI.

Bug Fixes

• Fixed ChatAPI race condition - The getPrefix() and getSuffix() methods were firing two separate async operations that could race, causing incomplete cache entries. Now uses a single atomic preload operation.

• Added ChatAPI preload on player connect - The ChatAPI cache is now preloaded when players connect, ensuring prefix/suffix data is available immediately for the first chat message.

• Improved cache handling - Added defensive guards to prevent partial cache entries (e.g., prefix-only entries with null suffix) from being stored, which could persist for the 30-second TTL.

• Added ChatAPI cleanup on disconnect - Player data is now properly invalidated from the ChatAPI cache when they disconnect.

Technical Details

The root cause was in ChatAPI.java where getPrefix() called both preload(uuid) and getPrefixAsync(uuid) as separate operations. If getPrefixAsync() completed first with an empty cache, it would create a broken cache entry with null values that persisted until TTL expiry.

Affected Files

• ChatAPI.java - Fixed race condition in getPrefix/getSuffix, improved updateCache
• HyperPermsPlugin.java - Added preload on connect and invalidate on disconnect

Upgrade Notes

This is a drop-in replacement. Simply replace your existing HyperPerms JAR with this version.

v2.3.3 - ChatAPI & Web Editor Fixes

What's Changed

Bug Fixes

• Fixed ChatAPI.getPrefix() returning empty - External plugins using the ChatAPI (like WerChat, HyFactions integrations) were sometimes getting empty prefixes due to timeout issues. Increased cache TTL and sync timeout for more reliable prefix/suffix retrieval.

• Fixed web editor null pointer exceptions - The /hp apply command would fail with "Cannot invoke getAsString() because return value is null" when the web editor API returned data with missing fields. Added comprehensive null-safety checks to all JSON parsing.

• Improved JSON parsing robustness - Manual permission entries in the web editor now handle multiple field name variations (node, permission, name) and gracefully skip invalid entries instead of crashing.

Technical Details

• ChatAPI cache TTL increased from 10s to 30s
• Sync fallback timeout increased from 100ms to 500ms
• Added automatic preload on cache miss for better subsequent calls
• Added safe JSON getter methods for defensive parsing

Note on HyFactions Chat Conflicts

If you're experiencing chat formatting issues with HyFactions, this is a plugin conflict where HyFactions overrides HyperPerms' formatting when showFactionNameInChat: true. The HyFactions plugin would need to add an option to disable its chat handling. HyperPerms is formatting correctly - HyFactions just overrides it afterward.

---

Full Changelog: v2.3.2...v2.3.3

v2.3.2 - Fix permissions, add resetgroups command

Bug Fixes

• Fix faction placeholders (%faction%, %faction_rank%, %faction_tag%) not resolving in chat
• Fix permission inheritance - inherited permissions from parent groups now work correctly
• Fix default group permission nodes - changed hytale.command.* to hytale.system.command.*

New Features

• Added /hp resetgroups --confirm command to reset all groups to plugin defaults

Note for Existing Servers

Run /hp resetgroups --confirm to update your groups with the correct permission nodes, or manually update from hytale.command.* to hytale.system.command.*

v2.3.1 - Fix faction placeholders, Fix permission inheritance

Bug Fixes

Faction Placeholders

Fixed an issue where faction placeholders (%faction%, %faction_rank%, %faction_tag%) were not resolving properly in chat.

Permission Inheritance

Fixed permission inheritance - inherited permissions from parent groups now work correctly with Hytale commands.