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

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

Configuration

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

{
  "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": {
    "type": "mariadb",
    "host": "localhost",
    "port": 3306,
    "database": "hyperperms",
    "username": "root",
    "password": "",
    "poolSize": 10,
    "useSSL": false
  }
}

Important: HyperPerms and Operator (OP) status on 0.5.2

On Hytale 0.5.2+, 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 0.5.2 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).

For Developers

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compileOnly 'com.github.HyperSystems-Development:HyperPerms:2.9.5'
}

HyperPermsAPI api = HyperPerms.getApi();

// Check permissions
User user = api.getUserManager().getUser(uuid).join();
boolean canBuild = user.hasPermission("world.build");

// Add contextual permission
Node node = Node.builder("world.build")
    .value(true)
    .withContext("world", "creative")
    .build();
user.addPermission(node);

// Create a group
Group admin = Group.builder("admin")
    .weight(100)
    .addPermission(Node.builder("*").build())
    .build();
api.getGroupManager().createGroup(admin);

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

Links

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

Part of the HyperSystems suite: HyperPerms | HyperEssentials | HyperFactions