Changelog
v2.5.1Track all changes, improvements, and fixes in HyperPerms releases.
Latest Release
v2.5.1 — Hytale-Native Permission Resolution
January 31, 2026
7 changesGitHub
Major version changes may include breaking changes. Always read the release notes before upgrading, especially for major versions.
Changed
(5)- 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.)
- "admin.*"
- "-admin.dangerous" # This still works
Fixed
(2)- 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
Fixed
(15)- 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
- Resolved chat prefix conflict when both plugins are installed
- Dynamic event priority based on HyFactions presence
- Output: [FactionTag] [RankPrefix] PlayerName: message
- 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
- Null-safe server root resolution in LuckPerms migrator
- Removed verbose debug logging spam
- HyperHomes: Added share, admin, and bypass wildcard expansions
- HyperWarps: Full wildcard expansion with bypass permissions
Fixed
(4)- 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
Added
(22)- ~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
- 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
- Preserved camelCase for hytale.editor.builderTools (case-sensitive!)
- Full editor permission tree: brush, prefab, selection, packs, history
- 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
Changed
(8)- 30 files modified with +3,095 / -689 lines*
- HYTALE_PERMISSIONS.md - Permission reference documentation
- PermissionAliases.java - Centralized alias management (988 lines)
- CaseInsensitiveSet.java - Hytale compatibility utility
- HyperPermsCommand.java - Complete refactor (+800 lines)
- PermissionRegistry.java - ~100 new permissions registered
- PermissionResolver.java - Alias-aware permission checking
- HyperPermsPermissionProvider.java - Alias expansion in provider
Fixed
(15)- 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
- 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
- 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
- Cleaned up default-groups.json to use proper Hytale permission nodes
Changed
(17)- 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
- 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
- HyperPerms.java - Added user loading on startup
- UserManagerImpl.java - Fixed race condition in loadUser()
- HyperPermsCommand.java - Awaited critical save operations
Changed
(11)- 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
- 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
- Added TabList cache invalidation
- Cleaned up debug logging
- Performance improvements to permission resolution
Fixed
(6)- 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.
- ChatAPI.java - Fixed race condition in getPrefix/getSuffix, improved updateCache
- HyperPermsPlugin.java - Added preload on connect and invalidate on disconnect
Changed
(7)- 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.
- 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
Added
(1)- Added /hp resetgroups --confirm command to reset all groups to plugin defaults
Fixed
(3)- Fix faction placeholders (%faction%, %factionrank%, %factiontag%) 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.
Added
(10)- Native prefix/suffix display in the server tab list
- New tabList config section with customizable format
- Uses same placeholders as chat (%prefix%, %player%, %suffix%, etc.)
- Automatic cache invalidation when permissions change
- New TabListAPI for external plugin integration
- Commands now support offline players via UUID
- /hp user addgroup {uuid} <group> creates user if needed
- /hp user setprimarygroup {uuid} <group> works for players who haven't joined
- /hp user setperm {uuid} <permission> works for offline players
- Perfect for Tebex commands using {id} placeholder
Fixed
(1)- Fixed web editor "type field is null" crash when fetching changes
Version Numbering
HyperPerms follows semantic versioning (MAJOR.MINOR.PATCH):
- MAJOR - Breaking changes that may require config updates
- MINOR - New features that are backwards compatible
- PATCH - Bug fixes and minor improvements
Stay Updated
Get notified about new releases
Stay up to date with the latest HyperPerms updates, features, and security patches.
Subscribe to updates