HyperPerms

The permission system for Hytale. Web editor, 11 server templates, plugin integrations, and everything you need out of the box.

Documentation | Web Editor | Discord | CurseForge

Version 3.0.0 targets Hytale Update 6 (0.6.0-pre.x) and does not run on 0.5.x. Update 6 changed PermissionProvider and the player-list packet in ways that cannot be supported from one build. Running Hytale 0.5.x? Stay on HyperPerms 2.10.x.

The headline change for operators: the whitelist is now the hytale.server.join permission. Grant it to a HyperPerms group to whitelist that group. See HYTALE_PERMISSIONS.md.

Features

Web Editor — Edit permissions in your browser at hyperperms.com. Drag-and-drop groups, visual inheritance graphs, smart autocomplete with 300+ permissions, and live chat preview. No port forwarding needed. Want to self-host? The editor is open source and can run offline on your own infrastructure.

11 Server Templates — Survival, RPG, factions, skyblock, prison, creative, SMP, towny, minigames, vanilla, and staff. One command gives you groups, permissions, inheritance, prefixes, and tracks.

Plugin Integrations — First-class support for VaultUnlocked, MMOSkillTree (200+ nodes), HyperFactions, PlaceholderAPI, MysticNameTags, and WerChat. Auto-detected, zero configuration.

Storage Backends — JSON (default), SQLite, or MariaDB/MySQL with HikariCP connection pooling for multi-server networks.

Contextual Permissions — Scope permissions per-world, per-gamemode, or per-server.

Wildcards & Negation — plugin.command.* matches all subpermissions. -hytale.command.spawn denies explicitly.

Tracks & Inheritance — Promotion/demotion tracks with weight-based group priority and unlimited inheritance depth.

Timed Permissions — Temporary permissions and group membership with automatic expiration (1d, 2h30m, 1w).

Analytics & Auditing — Track permission usage, view hotspots, and audit change history (requires SQLite).

Runtime Discovery — Automatically scans installed plugins and discovers their permission nodes. Discovered permissions appear in the web editor with "Installed" badges.

LuckPerms Migration — One-command import from LuckPerms (YAML, JSON, H2, MySQL/MariaDB). Automatic backup before migration.

Quick Start

1. Drop HyperPerms.jar in your mods/ folder
2. Start your server
3. Run /hp editor to open the web editor, or use commands:

/hp template apply survival # Instant rank hierarchy
/hp group create admin # Create a group
/hp group admin setperm * # Grant all permissions
/hp user Steve addgroup admin # Add player to group

Commands

Command	Description
/hp editor	Open web-based permission editor
/hp user <player> info	View player's groups and permissions
/hp user <player> setperm <perm> [value] [duration]	Set a permission (optionally temporary)
/hp user <player> addgroup <group> [duration]	Add player to group
/hp user <player> promote <track>	Promote on a track
/hp group create <name>	Create a new group
/hp group <name> setperm <perm> [value] [duration]	Set group permission
/hp group <name> parent add <parent> [duration]	Add parent group
/hp template list	List available templates
/hp template apply <name>	Apply a server template
/hp check <player> <perm>	Test a permission
/hp debug toggle <category>	Toggle debug logging
/hp backup create [name]	Create a backup
/hp migrate luckperms [--confirm]	Import from LuckPerms
/hp reload	Reload configuration

All Permissions

Permission	Description
hyperperms.command.*	Full admin access
hyperperms.command.user.*	User management
hyperperms.command.group.*	Group management
hyperperms.command.track.*	Track management
hyperperms.command.check.self	Check own permissions
hyperperms.command.check.others	Check other players' permissions

Configuration

Config file: mods/com.hyperperms_HyperPerms/config.json

View full config

{
"storage": {
"type": "json"
},
"cache": {
"enabled": true,
"maxSize": 10000,
"expireAfterAccessMinutes": 10
},
"defaultGroup": "default",
"webEditor": {
"enabled": true,
"apiUrl": "https://api.hyperperms.com"
},
"analytics": {
"enabled": false,
"trackChecks": true,
"trackChanges": true,
"retentionDays": 90
},
"console": {
"clickableLinksEnabled": true
}
}

Storage types:"json" (default), "sqlite", "mariadb", "mysql"

For MariaDB/MySQL, add connection details:

{
"storage": {
"type": "mariadb",
"host": "localhost",
"port": 3306,
"database": "hyperperms",
"username": "root",
"password": "",
"poolSize": 10,
"useSSL": false
}
}

Important: HyperPerms and Operator (OP) status

HyperPerms registers as the primary permission provider (it puts itself first while keeping Hytale's built-in provider registered). All permission decisions are made by HyperPerms.

Hytale determines operator status by group membership — internally it checks whether a player is in the hytale:Admin group. To make this work for HyperPerms-managed admins, HyperPerms automatically reports a player as being in hytale:Admin whenever they effectively have the * permission (e.g. via the bundled admin/owner groups). So granting a HyperPerms group the * node makes its members OP, recognized by Hytale and OP-gated features.

Manage everything through HyperPerms:

• Use /hp commands (e.g. /hp group create <name>), not Hytale's vanilla /perm or /setgroup — those operate on Hytale's built-in data, and /perm reload does not reload HyperPerms (use /hp reload).
• Grant admin/operator access by putting a player in a HyperPerms group that has the * node (the bundled admin/owner groups do). Hytale's vanilla /op self is advisory-disabled while HyperPerms is active.

Optional: SQLite & Analytics

SQLite enables analytics tracking and audit logs. It's not bundled to keep the JAR small (~7MB vs ~20MB).

Enable SQLite features

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

Without SQLite: Everything works fine — analytics is simply disabled and JSON storage is used.

Analytics commands:

• /hp analytics summary — Permission health overview
• /hp analytics hotspots — Most checked permissions
• /hp analytics audit — Change history

For Developers

Maven Dependency (JitPack)

Add HyperPerms as a dependency to build integrations:

repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.HyperSystems-Development:HyperPerms:2.9.5'
}

API Usage

HyperPermsAPIapi = HyperPerms.getApi();
// Check permissionsUseruser = api.getUserManager().getUser(uuid).join();
booleancanBuild = user.hasPermission("world.build");
// Add contextual permissionNodenode = Node.builder("world.build")
.value(true)
.withContext("world", "creative")
.build();
user.addPermission(node);
// Create a groupGroupadmin = Group.builder("admin")
.weight(100)
.addPermission(Node.builder("*").build())
.build();
api.getGroupManager().createGroup(admin);

Building from Source

Requirements: Java 25, Gradle 9.3+, Hytale 0.6.0+

The Hytale Server API is resolved automatically from maven.hytale.com. The pre-release channel is the default, because 3.x targets Update 6 (0.6.0-pre.x); -Phytale_channel=release or ./gradlew buildRelease is retained for when Update 6 promotes to the release channel and will not compile before then. PlaceholderAPI comes from repo.helpch.at. VaultUnlocked is a compile-only soft dependency supplied as a jar in libs/ (from TheNewEconomy/VaultUnlocked-Hytale).

./gradlew shadowJar
# Output: build/libs/HyperPerms-<version>.jar

See CONTRIBUTING.md for full development setup and contribution guidelines.

Links

• Documentation - Full wiki and guides
• Discord - Support & community
• Issues - Bug reports & features
• Releases - Downloads

---

Part of the HyperSystems suite: HyperPerms | HyperEssentials | HyperFactions